English README: en/README.md
你是否每天都在大量使用 Cursor、Claude Code、Trae 等 AI 编码工具，却感觉交付结果不稳定？或者经常被 AI 牵着走，不知道协作的问题到底出在哪里？
AI Growth Mirror 是一面本地优先的 Agentic 操作成熟度评估系统。它静默、安全地读取你本机已有的 AI 编码会话历史，通过"四证法"和"六轴底盘"算法，将你模糊的协作感觉转化为可观察、可解释、可复盘的可视化成长报告。它不是"好看的 AI 使用海报"，而是帮你打破协作瓶颈、沉淀高杠杆技术资产的成长产品。
AI 工具的发展正在经历三个阶段转型，评估重心也在随之迁移：
阶段一（Copilot） 阶段二（Agentic） 阶段三（Autonomous）
───────────────────── ───────────────────────── ──────────────────────────
人写代码，AI 补全 人定目标，AI 执行 人做战略，AI 自主完成
intent 很重要 execution 才是核心 评估对齐与控制能力
"Prompt 写得好不好" "能否驱动 AI 稳定交付" "能否建立可信任的 AI 系统"
AI Growth Mirror 的定位：不是 Prompt 打分器，而是 Agentic 操作成熟度评估。 从 v0.7 开始，评估重心从「你的 Prompt 写得有多完整」迁移到「你能否把 AI 变成稳定可复用的生产力系统」。
AI Growth Mirror 拒绝无意义的单纯统计（如消息数、敲代码行数），而是用**"四证法"**真实映射你的人机协作水平：
- 🎯 Context Frame (上下文边界): 是否在协作启动与对齐阶段，为任务建立清晰的目标、约束和验收标准？（可通过单轮精准输入或多轮交互澄清完成）
- 🔗 Flow Orchestration (连续流编排): 是否驱策 AI 连续解决复杂问题，而不是每一步都靠人工接管？
- 🔁 Proof Loop (闭环验证): 是否把构建、测试与纠偏行为深度融入人机交互中？
- 📦 Method Asset (方法资产化): 是否将有效的实践提炼为 Rule、Skill、Workflow 等高杠杆资产并产生复用？
四证法是方法论入口（4 个好记的协作支柱），下面的六轴雷达是它的度量展开。映射关系：
- Context Frame → 协作框定
- Flow Orchestration → 协作驱动 + 实现下潜（既要连续推进，也要真正下潜到实现）
- Proof Loop → 交付收口 + 恢复推进（构建/测试收口 + 偏航后的纠偏）
- Method Asset → Agentic 系统化
每一期生成的评估结果都会投射到六轴协作雷达（协作指数由此计算），它是上方「四证法」的可度量展开：
| 协作能力轴 | 权重 | 衡量内容 |
|---|---|---|
协作框定 (collaboration_framing) |
14% | 协作启动质量，包含目标锁定速度、主动澄清率与有效任务契约（v1.0.0升级） |
协作驱动 (execution_driving) |
25% | 连续自主推进、结构化工作流，以及产生已验证结果的委派（Agentic 主战场） |
实现下潜 (implementation_depth) |
19% | 实现会话、代码验证、任务达成与有上限的文件覆盖；原始文件量不直接加分 |
交付收口 (delivery_closure) |
19% | 任务完成率、验证行为、测试/构建/脚本验证与契约履约表现 |
恢复推进 (adaptive_recovery) |
10% | 只在真实偏航或报错机会出现时，衡量纠偏和回到正轨的质量 |
Agentic 系统化 (agentic_system) |
13% | Skill/Workflow/MCP/Subagent 等方法能否形成复用且已验证的结果 |
为什么这样调整：见 v1.0.2 可解释评估设计。评估政策
2.0将缺失证据标记为不可用并显示覆盖率；token、commit、工具、模型和子代理数量仅作上下文，不直接奖励成熟度。
从 v0.7 起，系统不再围绕"Prompt 写得好不好"做单点判断，而是用 协作框定、协作驱动、实现下潜、交付收口、恢复推进、Agentic 系统化 六轴评估真实协作成熟度。v0.8 将 collaboration_framing 定稿为正式轴，并把协作启动质量从"首轮完备度"扩展到多轮目标锁定能力。
v0.8 新增 goal_locking_speed：通过 turns_until_first_file_write 观察用户能否快速驱动 AI 锁定目标、边界与可交付路径。支持精细工具流的 reader 会记录首次写入前的用户轮数；缺少工具流时该分量标记为不可用，不会猜测或伪造分数。
报告底层会构建六维证据图：任务意图、方法使用、上下文、执行路径、收口状态与人工干预。训练建议不再是固定文案，而是由真实短板、纠偏模式和证据图生成 Rule / Skill / Workflow / Checklist 形式的 Action Contract。
v1.0.0 起，系统会区分用户显式契约、Skill/Rule/Workflow 契约、Agent 派生契约与后置纠偏契约，避免把“已有全局规则但首轮没手写验收”误判为纯粹的协作框定缺失。
- Action Contract 回看：自动识别上一期建议在本期的改善效果（improved / partial / unchanged）
- 成长轨迹：六轴评分 + 摩擦变化的逐期 delta，SVG 趋势折线 + 变化箭头
- CLI
status：ai-growth-mirror status即时显示样本进度 + 本周练习提示（< 100ms）
一键扫描，自动识别并聚合以下 12 款 AI 工具：
- 国际主流：Claude Code、Codex、Cursor、Gemini、OpenCode、Cline、Kilo Code、DeepSeek Harness
- 国产先锋：CodeBuddy、Trae、QCoder、ZCode
DeepSeek Harness 与 ZCode 都按用户可见根任务归一：子会话证据只向根任务汇总一次，避免 Agent/Subagent 重复计分。未知版本或缺表会明确拒绝读取；ZCode 不读取包含请求/响应正文的 model-I/O 文件。
每个轴公开 policy 版本、证据覆盖率、可用分量、主要支撑与缺口原因。用户不仅知道“分数是什么”，也能看到“为什么”“缺了什么证据”“下一期该如何验证”；跨 policy 快照不计算伪精确 delta。
默认使用本地规则引擎离线分析；--no-llm 可保证分析阶段不发起外部 LLM 请求。启用 llm 模式时，只会发送经过统一边界裁剪与规则脱敏的有限会话摘录，而非完整代码文件；系统会遮盖常见密钥、邮箱和本机路径，但无法保证识别任意业务机密。generate --redact 另用于脱敏 HTML 报告、Sidecar、分享卡与快照中的路径和代码隐私。
生成 ai-growth-mirror.html 后双击即可本地打开，无需部署。报告按「诊断 → 训练 → 追踪」组织，侧边栏可快速跳转各区块。
首屏一眼看懂：等级 · 协作指数 · 下一步练什么。支持浅色 / 深色主题切换。
| 浅色主题 | 深色主题 |
|---|---|
 |
 |
六轴协作雷达 + 协作指数趋势折线 + Top 3 短板与可执行行动建议。
四维度协作画像（启动 / 推进 / 收口 / 复用），帮你看见自己的 AI 协作「打法」而非只看分数。
你在做什么（项目、目标类型、工具与语言）+ 双节奏切换等协作节律洞察。
从高分会话中提炼可复用的协作范式（深度委托、工具链编排、结构化执行），直接迁移到下一类相似任务。
- Python 3.12+
# 克隆仓库后在根目录运行：
pip install -e .
# 默认已支持 OpenAI 兼容网关（如 deepseek、openai）；仅 claude / gemini 需额外安装：
pip install -e ".[llm]"也可使用 uv（与仓库 uv.lock 一致）：
# 默认已含 openai SDK，支持 deepseek / openai / openai_compatible 等网关的 LLM 语义诊断
uv sync
# 仅在使用 claude、gemini provider 时需额外安装 Anthropic / Gemini SDK
uv sync --extra llmcp config.example.yaml config.yaml
# 编辑 config.yaml 填入 LLM Provider、API Key、本地 Agent 资产扫描根目录任选一种执行方式（在你的工作区目录运行，通常为项目仓库根目录）：
cd /path/to/your/project-workspace
# 方式 A：已 pip install -e . 安装 CLI 入口
ai-growth-mirror generate
# 方式 B：不安装全局命令，在 ai-growth-mirror 仓库根目录用 Python 模块
python -m ai_growth_mirror.cli generate
# 方式 C：uv 环境（在 ai-growth-mirror 仓库根目录）
uv run python -m ai_growth_mirror.cli generate查看版本：
python -m ai_growth_mirror.cli --version
# 或（已安装 CLI 时）
ai-growth-mirror --version运行完成后，您的当前目录下将输出：
ai-growth-mirror.html: 个人 Agentic 成熟度交互式分析主报告。ai-growth-mirror.json: 结构化 Evidence Sidecar（含 Agentic Evidence Graph、覆盖率与统计证据）。ai-growth-mirror.summary.json: 面向分享卡、二次消费和自动化集成的稳定摘要契约。ai-growth-mirror-share.html: 对外分享脱敏卡片。ai-growth-mirror-archive/: 快照存档目录，第二次运行时将自动激活「成长轨迹对比」（本期 vs 上一期）。
以下示例用 CLI 入口；未全局安装时，将 ai-growth-mirror 替换为 python -m ai_growth_mirror.cli（uv 用户可用 uv run python -m ai_growth_mirror.cli）。
- 查看本周样本进度：
ai-growth-mirror status - 指定工具过滤：
ai-growth-mirror generate --tools cursor,trae - 锁定时间窗口：
ai-growth-mirror generate --since 2026-01-01 --until 2026-06-30 - 离线规则引擎分析（零外部网络调用与费用）：
ai-growth-mirror generate --session-read-mode heuristic - 过滤分析范围（按特定 Repository、目录或关键字过滤）：
ai-growth-mirror generate --repo app-repo --dir ~/projects/app - 手工对比历史快照：
ai-growth-mirror compare <left_snapshot_id> <right_snapshot_id> - 清理过期缓存：
ai-growth-mirror cache prune
对于想要深度定制、贡献 Adapter 或调试算法的开发者，请详细参阅我们的 Canonical 文档（英文版见 en/README.md 与 docs/en/README.md）：
- 分层依赖与架构总纲
- 产品路线图
- v1.0.2 DDD 可解释评估与新工具接入
- ADR：v1.0.2 单一评估政策与根任务反腐层
- v1.0.1 可信与韧性加固
- ADR：v1.0.1 可信边界与持久化决策
- v1.0.0 有效任务契约与 Agentic 报告校准
- v0.8.1 协作效能公允度升级与冷启动性能优化
- v0.8.0 协作框定与目标锁定速度设计
- v0.7.0 Agentic 体系重构设计
- v0.6.0 训练闭环设计
- 产品语气、命名与安全脱敏规范
- 参与贡献指南
本项目基于 MIT License 协议发布。