═══════════════════════════════════════════════════════════
  古立特 Gridman v1.9.0 — 使用说明【公开版】
  财税超级特工 | Hyper Agent for Finance
  本文件随公开版分发（35 个知识模块，不含 songs / political_economy）
═══════════════════════════════════════════════════════════

目录：
  1. 古立特是什么
  2. 你拿到了什么
  3. 安装（一句话搞定）
  4. 各平台放置位置
  5. 启用市场数据工具（可选）
  6. 配置 OCR 文档识别（可选）
  7. 适配环境
  8. 常见问题


═══════════════════════════════════════════════════════════
1. 古立特是什么
═══════════════════════════════════════════════════════════

古立特 = 知识层 + 工具层

  知识层（SKILL.md + references/）
    - 35 个财税专业模块：会计准则、税法、审计、内控、投行、
      ESG、政府会计、财务造假识别、经济法、财务 BP……
    - 纯 Markdown 文件，AI 读了就懂财税
    - 不需要 Python，不需要安装，放进去就能用

  工具层（payload/ 里的 .whl 安装包）
    - 35 个 Python 计算工具：银行调节、账龄分析、审计抽样、
      截止测试、函证生成、纳税调整、财务比率……
    - 通过 MCP 协议被 AI 调用——不是传统 App，没有界面，
      是 AI 的后台工具箱
    - 让古立特从"只会说"变成"能动手"

两层可以分开用：
  - 只用知识层 = 纯财税知识问答（零配置）
  - 知识层 + 工具层 = 知识 + 计算（需装一次 uv）


═══════════════════════════════════════════════════════════
2. 你拿到了什么
═══════════════════════════════════════════════════════════

  gridman/
  ├── SKILL.md              ← 古立特主文件（人格+路由+知识索引）
  ├── INSTALL.md            ← 安装固件（AI 读了自动装工具层）
  ├── AI适配引导.md          ← 跨平台接入指南（AI 读的）
  ├── README.md             ← 项目说明
  ├── 使用说明.txt           ← 本文件（给人看的）
  ├── references/           ← 35 个知识模块
  └── payload/
      └── gridman_mcp-1.9.0-py3-none-any.whl  ← 工具层安装包


═══════════════════════════════════════════════════════════
3. 安装（一句话搞定）
═══════════════════════════════════════════════════════════

【第一步：放置知识层】

  把整个 gridman/ 文件夹放到你的 AI Agent 能读到的位置
  （具体位置见第 4 节）。

  放好后，对 AI 说任何财税问题，古立特就能回答了。
  到这一步，知识层已经可用。

【第二步：安装工具层（可选，让古立特能"动手"）】

  对 AI 说一句：

    "装古立特" 或 "安装 MCP" 或 "install gridman"

  AI 会自动读取 INSTALL.md，按步骤执行：
    1. 检测 uv 是否已装（没有就帮你装）
    2. 在 payload/ 里找到安装包
    3. 写入当前 Agent 的 MCP 配置
    4. 提示你重启 Agent

  重启后看到 "gridman Connected (35 tools)" 就成功了。

  ⚠️ 首次连接 uvx 会自动下载依赖（10-60秒），属正常现象。
  ⚠️ 需要联网（下载依赖用），之后离线也能用。


═══════════════════════════════════════════════════════════
4. 各平台放置位置
═══════════════════════════════════════════════════════════

  ┌──────────────┬──────────────────────────────────────────┐
  │ AI Agent     │ 把 gridman/ 文件夹放到                    │
  ├──────────────┼──────────────────────────────────────────┤
  │ Kiro         │ 工作区 .kiro/skills/gridman/              │
  │ Cursor       │ 项目根目录下（AI 会自动发现）              │
  │ Claude Code  │ 项目根目录下                              │
  │ Codex        │ 项目根目录下                              │
  │ Windsurf     │ 项目根目录下                              │
  │ OpenClaw     │ 平台技能目录                              │
  └──────────────┴──────────────────────────────────────────┘

  核心要求只有一条：SKILL.md 和 references/ 必须在同一级目录。


═══════════════════════════════════════════════════════════
5. 启用市场数据工具（可选）
═══════════════════════════════════════════════════════════

A 股行情/K 线/财务数据这 4 个工具依赖 akshare（较重），
默认不装。需要股票数据时，让 AI 帮你改 MCP 配置：

  在 args 的 whl 路径后面加 [market]（无空格）

  改前："--from", "路径/gridman_mcp-1.9.0...whl"
  改后："--from", "路径/gridman_mcp-1.9.0...whl[market]"

其余 31 个工具不需要它，默认配置即可。


═══════════════════════════════════════════════════════════
6. 配置 OCR 文档识别（可选）
═══════════════════════════════════════════════════════════

document_ocr（识别扫描版 PDF/图片）需要 MinerU 云端 API Token。
其他 33 个工具不需要。

获取 Token（免费）：
  1. 打开 https://mineru.net → 登录
  2. 顶部 → API → 左侧"智能解析 → API 管理"
  3. 创建 Token → 复制

让 AI 帮你把 Token 加进 MCP 配置的 env 字段即可。

注意：
  - Token 有效期 90 天，到期重新创建
  - 每天 1000 页免费额度
  - 不配 Token 不影响其他工具


═══════════════════════════════════════════════════════════
7. 适配环境
═══════════════════════════════════════════════════════════

  ⭐⭐⭐ 最佳：Kiro / Cursor / Claude Code
    → Skill 文件读取 + MCP 工具调用 + 文件操作，全部完美支持

  ⭐⭐ 可用：Codex / Windsurf / Cline
    → 支持 MCP 的均可接入

  ⭐ 基本可用：OpenClaw / LobeChat / Cherry Studio
    → 知识问答能用，但路由判断和工具调用体验有限
    → 这类平台的技能加载机制偏简单，对古立特这种
      "34 模块 + 巨型路由表 + MCP 联动"的复杂技能支持有限

  总结：古立特最适配"以 IDE 为主体的 AI Agent"。


═══════════════════════════════════════════════════════════
8. 常见问题
═══════════════════════════════════════════════════════════

Q: 说了"装古立特"但 AI 没反应？
A: 确认 SKILL.md 和 INSTALL.md 在 AI 能读到的位置。
   Kiro 要放在 .kiro/skills/ 下才会自动加载。
   其他 Agent 可能需要手动让 AI "读一下 INSTALL.md"。

Q: 重启后显示 "Connection Failed"？
A: 按顺序排查：
   1. uv 装了吗？终端跑 uv --version
   2. 第一次连接要下载依赖，等 10-60 秒
   3. whl 路径对不对？让 AI 重新检测 payload/ 里的文件
   4. 网络能否连外网（首次需要下载依赖）

Q: 不装工具层能用吗？
A: 能。知识层零配置可用——问财税问题、准则判断、税务筹划思路
   都只需要知识层。工具层是"让古立特能算数、出文件"的增强。

Q: 支持 Mac / Linux 吗？
A: 全支持。uv 和 uvx 跨平台，配置完全一样。

Q: 提示 "akshare 未安装"？
A: 只影响 4 个市场数据工具。需要 → 按第 5 节加 [market]。
   不需要股票数据 → 忽略。

Q: 提示 "MINERU_API_TOKEN 未配置"？
A: 只影响 OCR。需要 → 按第 6 节配 Token。不需要 → 忽略。

Q: 古立特能做什么？不能做什么？
A: 能做：知识问答、准则判断、底稿计算、异常标记、报表校验、
   函证生成、税务自查、估值建模思路、经营分析框架……
   不能做：实地盘点、询问管理层、检查原件、形成正式审计意见、
   签字盖章。古立特是"半自动"——算力和知识它出，判断和签字你来。

Q: 古立特的回答能直接用吗？
A: 古立特提供专业知识指引和工作辅助，不构成正式审计意见、
   税务建议或法律意见。所有结论需以专业胜任能力复核确认。


═══════════════════════════════════════════════════════════
  作者：真寻Charlotte
  版本：1.9.0（公开版）
  许可证：CC BY-NC-SA 4.0（知识层）/ MIT（工具层源码）
  更新日期：2026-06-08
═══════════════════════════════════════════════════════════
