🌟 IMA知识库CLI工具 v3.1.2


> 🔥 基于Chrome DevTools实时分析开发的IMA官方API兼容工具
> 🎯 彻底解决认证刷新问题，确保长期稳定运行
> ✨ v3.1全新架构：代码质量大幅提升，性能优化，内存安全
> 🤖 集成Agent Skills：Claude Code原生支持，自动化工作流

---

📋 项目概述

IMA知识库CLI工具是一个基于Chrome DevTools实时分析开发的命令行工具，完全兼容IMA官方API。经过v3.1架构优化，代码质量显著提升，具备完善的错误处理、优雅的资源管理和长期稳定运行能力。

$3

API兼容性:
- ✅ 正确端点: /cgi-bin/auth_login/refresh
- ✅ 完整参数: user_id, refresh_token, token_type: 14
- ✅ 官方格式: x-ima-cookie 头部认证
- ✅ 智能刷新: 自动检测token过期并刷新

v3.1架构优化:
- ✅ 统一错误处理系统（8个错误类）
- ✅ 常量配置模块化（constants.js）
- ✅ 完整JSDoc文档（100%覆盖）
- ✅ 异步I/O操作（性能提升）
- ✅ 内存安全（cleanup机制）
- ✅ 优雅退出（SIGINT/SIGTERM处理）

---

🚀 快速开始

$3

- Node.js 14.0+
- 有效的IMA账号

$3

方法 1: 从 npm 安装（推荐）⭐
``bash


全局安装

npm install -g ima-cli

配置认证

ima update-auth

开始使用

ima help
ima list

查询知识库

ima rk3506 "CPU架构"
`

方法 2: 使用 npx（无需安装）
`bash


直接运行，无需安装


npx ima-cli help
npx ima-cli list
npx ima-cli rk3506 "引脚定义"
`

方法 3: 从源码安装
`bash


1. 克隆仓库

git clone https://gitcode.com/u013122784/ima-cli.git
cd ima-cli

2. 安装依赖

npm install

3. 配置认证信息

node update-cookies.js

4. 验证配置

node ima-cli.js auth status

5. （可选）全局链接

npm link
`

$3

`bash

使用 npm 安装版本

ima <知识库名称> <问题>

或使用 npx

npx ima-cli <知识库名称> <问题>

或使用源码版本

node ima-cli.js <知识库名称> <问题>

示例

ima rk3506 rk3506有几个CPU核心
ima 个人知识库 如何使用这个工具
`

---

📚 文档体系

$3

- README.md - 本文档，项目概述和快速开始
- CLAUDE.md - Claude Code开发指南，架构说明
- CODE_QUALITY_REPORT.md - 代码质量评估报告 (69/100)

$3

- OPTIMIZATION_SUMMARY.md - v3.1架构优化总结
- FIRST_BATCH_OPTIMIZATION.md - 第一批优化报告
- ARCHITECTURE.md - 详细架构说明

$3

- Skills README - Skills 快速安装指南
- Skills 安装指南 - 完整安装说明
- 快速测试指南 - 5分钟测试验证
- Skills 验证报告 - 100%符合规范

$3

- cookie-data.json.template - 认证配置模板
- QUICK_REFERENCE.md - 快速参考卡

---

🔌 Claude Agent Skills

本项目包含符合 Agent Skills 开放标准 的 Claude Skills，可以与 Claude Code、Claude Apps 和 Claude API 无缝集成。

$3

Agent Skills 是包含指令、脚本和资源的技能包，Claude 会在相关任务中自动加载它们。

特性:
- ✅ Composable - Skills 可自动组合使用
- ✅ Portable - Claude Code、Apps、API 通用
- ✅ Efficient - Progressive Disclosure 设计，按需加载
- ✅ Powerful - 包含可执行代码处理复杂任务
- ✅ Standardized - 符合 Agent Skills 开放标准

$3

#### 1. ima-knowledge-base - 知识库查询和搜索

功能: 查询和搜索 IMA 知识库

包含: 4 个 scripts + 2 个参考文档

`bash


列出知识库

node .claude/skills/ima-knowledge-base/scripts/list.js

查询单个知识库

node .claude/skills/ima-knowledge-base/scripts/query.js rk3506 "CPU架构"

跨知识库搜索

node .claude/skills/ima-knowledge-base/scripts/search.js "引脚定义"
`

#### 2. ima-auth-management - 认证管理

功能: 管理 IMA API 认证令牌

包含: 4 个 scripts + 1 个参考文档

`bash


检查认证状态

node .claude/skills/ima-auth-management/scripts/check-status.js

刷新访问令牌

node .claude/skills/ima-auth-management/scripts/refresh-token.js

首次设置认证

node .claude/skills/ima-auth-management/scripts/setup-wizard.js
`

#### 3. ima-system-maintenance - 系统维护

功能: 系统健康检查和维护

包含: 7 个 scripts + 2 个参考文档

`bash


健康检查

node .claude/skills/ima-system-maintenance/scripts/health-check.js

刷新缓存

node .claude/skills/ima-system-maintenance/scripts/cache-refresh.js

备份配置

node .claude/skills/ima-system-maintenance/scripts/backup.js

API连接测试

node .claude/skills/ima-system-maintenance/scripts/connection-test.js
`

$3

共享工具模块:
- path-utils.js - 智能路径解析，100%准确率
- timeout-utils.js - 网络请求超时保护

验证报告:
- 100% 符合 Agent Skills 开放标准
- 所有 15 个脚本可执行
- 完整的 YAML frontmatter

$3

Claude Code 会自动识别并加载相关 Skills：

`bash


Claude 会自动触发相应的 Skill

claude "查询 rk3506 知识库关于 CPU 架构的信息"

→ 自动使用 ima-knowledge-base skill

claude "检查我的认证状态"

→ 自动使用 ima-auth-management skill

claude "运行系统健康检查"

→ 自动使用 ima-system-maintenance skill

`

$3

- Skills README - Skills 完整文档
- 快速开始 - 5 分钟上手指南 ⭐
- 部署指南 - 部署和配置说明
- Agent Skills 规范 - 开放标准

---

🎯 核心功能

$3

`bash

npm 安装版本

ima rk3506 你想问的问题

npx 版本

npx ima-cli rk3506 你想问的问题

源码版本

node ima-cli.js rk3506 你想问的问题

支持模糊匹配

ima rk350 rk3506是什么
`

$3

`bash
ima auth status # 检查认证状态
ima auth refresh # 手动刷新认证
`

$3

`bash
ima list # 列出所有可用知识库
ima refresh # 刷新知识库ID缓存
`

$3

`bash
ima help # 显示完整帮助
`

---

✨ v3.1.2 新特性

$3

完整的 Claude Code 支持:
- ✅ 3 个 Agent Skills（知识库查询、认证管理、系统维护）
- ✅ 15 个可执行脚本
- ✅ 100% 符合 Agent Skills 开放标准
- ✅ Progressive Disclosure 设计，按需加载
- ✅ 自动任务识别和执行

共享工具模块:
- ✅ path-utils.js - 智能路径解析（多级fallback）
- ✅ timeout-utils.js - 网络请求超时保护
- ✅ 路径准确率从 60% 提升到 100%
- ✅ 健康检查从 ❌ 提升到 ✅
- ✅ 备份成功率从 0% 提升到 75%

$3

一键安装:
- ✅ 发布到 npm registry
- ✅ 支持全局安装 npm install -g ima-cli
- ✅ 支持 npx 直接运行
- ✅ 自动包含 Agent Skills
- ✅ 完整的文档体系

安装命令:
`bash
npm install -g ima-cli # 全局安装
npx ima-cli help # 无需安装
`

$3

新增文档:
- Skills 安装指南（3种安装方法）
- 快速测试指南（5分钟验证）
- Skills 验证报告（100%合规）
- 多个测试和修复报告

---

✨ v3.1.1 新特性

$3

1. 模块化设计
`
ima-cli/
├── ima-cli.js # 主程序（优化重构）
├── ima-auth-manager.js # 认证管理（内存安全）
├── constants.js # 常量配置（新增）
├── errors.js # 错误处理（新增）
├── update-cookies.js # 配置工具
└── cookie-data.json # 认证数据（需自行配置）
`

2. 统一错误处理
`javascript
// 8个专用错误类
IMAError // 基类
├── AuthError // 认证错误
├── TokenExpiredError // Token过期
├── KnowledgeBaseError // 知识库错误
├── NetworkError // 网络错误
├── ConfigError // 配置错误
├── APIResponseError // API错误
└── ValidationError // 验证错误
`

3. 完整的JSDoc文档
- 所有公共方法100%覆盖
- 参数类型和返回值说明
- 异常情况文档化

$3

- 异步I/O: 使用 fs.promises 避免阻塞
- JSON优化: 减少50%的序列化操作
- 智能缓存: 24小时知识库ID缓存
- 流式处理: SSE数据流式处理

$3

- 内存管理: cleanup()方法防止内存泄漏
- 全局错误处理: unhandledRejection捕获
- 优雅退出: SIGINT/SIGTERM信号处理
- 资源清理: 自动释放定时器和引用

---

📊 代码质量

$3

| 维度 | 得分 | 等级 |
|------|------|------|
| 代码架构 | 78/100 | 🟢 良好 |
| 代码质量 | 65/100 | 🟡 中等 |
| 安全性 | 65/100 | 🟡 中等 |
| 性能 | 80/100 | 🟢 优秀 |
| 可维护性 | 70/100 | 🟡 中等 |
| 最佳实践 | 72/100 | 🟡 中等 |
| 综合评分 | 69/100 | 🟡 及格 |

详细评估请查看 CODE_QUALITY_REPORT.md

$3

`
代码行数: ~2,500行
文件数量: 6个核心文件
测试覆盖: 0% (待改进)
文档覆盖: 100% JSDoc
重复代码: <5%
平均方法长度: <50行
`

---

📊 版本历史

| 版本 | 日期 | 主要特性 |
|------|------|----------|
| v3.1.2 | 2026-01-13 | 🤖 Agent Skills、npm发布、路径修复 |
| v3.1.1 | 2026-01-12 | 🔧 第一批优化：内存安全、性能提升、错误处理 |
| v3.1 | 2026-01-12 | ✨ 架构优化：常量提取、错误系统、JSDoc文档 |
| v3.0 | 2026-01-12 | 🎉 基础版本：Chrome DevTools API分析 |
| v2.0.2 | 2025-11-03 | 📚 完整文档体系 |
| v2.0.1 | 2025-11-03 | 🔬 技术探索历程 |
| v2.0.0 | 2025-11-03 | 🚀 Chrome DevTools突破 |

$3

新增功能:
- ✅ 集成 Agent Skills（3个skills，15个scripts）
- ✅ 发布到 npm registry
- ✅ 添加 path-utils.js 和 timeout-utils.js
- ✅ 修复所有路径解析问题

新增文档:
- Skills 安装指南
- 快速测试指南
- Skills 验证报告
- 多个测试和修复报告

改进指标:
- 路径准确率: 60% → 100%
- 健康检查: ❌ → ✅
- 备份成功率: 0% → 75%
- Agent Skills 规范符合性: 100%

$3

新增文件:
- constants.js - 集中管理所有配置常量
- errors.js - 统一的错误处理系统
- CLAUDE.md - Claude Code开发指南
- CODE_QUALITY_REPORT.md - 代码质量评估报告
- OPTIMIZATION_SUMMARY.md - 优化总结
- FIRST_BATCH_OPTIMIZATION.md - 第一批优化报告

删除文件:
- ima-cli-fixed-v2.1.js (重复文件)
- ima-auth-manager-fixed-v2.js (重复文件)

代码改进:
- 净减少 1,153 行代码
- 方法复杂度从 220行 降至 <50行
- 添加全局错误处理和优雅退出
- 修复内存泄漏风险

---

🔧 技术架构

$3

`mermaid
graph TB
A[ima-cli.js
主程序] --> B[constants.js
常量配置]
A --> C[errors.js
错误处理]
A --> D[ima-auth-manager.js
认证管理]

D --> E[自动token刷新]
D --> F[错误恢复]
D --> G[资源清理]

A --> H[SSE流式处理]
A --> I[知识库缓存]
A --> J[智能路由]
`

$3

- 认证刷新: /cgi-bin/auth_login/refresh
- 知识库查询: /cgi-bin/assistant/qa
- 知识库列表: /cgi-bin/knowledge_tab_reader/get_home_page_data

$3

- Token有效期: 7200秒 (2小时)
- 自动刷新: 提前5分钟
- 智能检测: 每30分钟检查
- 优雅降级: 自动fallback机制

---

🌟 使用场景

$3


`bash

快速查询技术文档

node ima-cli.js rk3506 UART引脚定义

集成到脚本

./query-kb.sh "rk3506" "CPU架构"
`

$3

`bash

文献资料查询

node ima-cli.js 论文库 "深度学习最新进展"

知识整理

node ima-cli.js 笔记 "总结本周学习内容"
`

$3

`bash

内部知识库查询

node ima-cli.js 技术文档 "部署流程"

自动化信息获取

node ima-cli.js 运维手册 "故障排查步骤"
`

---

🔍 示例输出

$3

`bash
$ node ima-cli.js rk3506 rk3506有几个CPU核心

🔍 正在搜索知识库 "rk3506"...
❓ 问题: rk3506有几个CPU核心
============================================================
🆔 知识库ID: 7315672614843264
🤖 正在思考，请稍候...
📋 响应状态: 200
🚀 QA会话已开始
📚 找到 21 篇相关文档

根据提供的文档内容，RK3506包含以下处理器核心：

• 3个ARM Cortex-A7核心：构成主应用处理器（AP）。
• 1个ARM Cortex-M0核心：作为微控制器单元（MCU）。

因此，RK3506总计有4个CPU核心（3个A7 + 1个M0）。

✅ QA会话已完成

📊 统计信息:
知识库: rk3506 (ID: 7315672614843264)
找到文档: 21 篇
答案长度: 492 字符
动态ID: ✅
认证管理器: ✅
`

$3


`bash
$ node ima-cli.js list

📚 IMA 知识库列表 (优化版本 v3.1):
============================================================
1. 个人知识库
🆔 ID: 0019eda859c051df

2. rk3568
🆔 ID: 7410302605855693

3. rk3506
🆔 ID: 7315672614843264

... (共12个知识库)
`

---

🤝 贡献指南

我们欢迎各种形式的贡献！

$3

1. 报告问题: 使用 Issues 报告bug
2. 提交代码: Fork项目，创建分支，提交Pull Request
3. 改进文档: 完善文档和示例
4. 分享经验: 分享使用经验和建议

$3

详见 CLAUDE.md - Claude Code开发指南

$3

- 使用ES6+特性
- 添加完整JSDoc注释
- 遵循现有的代码风格
- 确保所有功能通过测试

---

🚧 改进计划

$3

- [ ] 移除硬编码敏感数据
- [ ] 实施Cookie加密存储
- [ ] 添加基础单元测试

$3

- [ ] 提升测试覆盖率达到60%
- [ ] 实现日志系统
- [ ] 代码质量提升至75分

$3

- [ ] TypeScript迁移
- [ ] CI/CD流程
- [ ] 性能监控系统

详见 CODE_QUALITY_REPORT.md

---

📄 许可证

本项目基于MIT许可证开源，详见LICENSE文件。

---

🙏 致谢

- 感谢IMA平台提供的强大知识库服务
- 感谢Chrome DevTools团队的优秀工具
- 感谢Claude Code提供的开发支持
- 感谢所有参与测试和反馈的用户

---

🔗 相关链接

- IMA官方网站
- 代码仓库
- Chrome DevTools文档
- Node.js官方文档

---

📞 支持

遇到问题？

1. 查看 文档体系
2. 阅读 CODE_QUALITY_REPORT.md
3. 提交 Issue

---