[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-1966":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":14,"openIssues":15,"contributorsCount":15,"subscribersCount":15,"size":15,"stars1d":15,"stars7d":15,"stars30d":15,"stars90d":15,"forks30d":15,"starsTrendScore":15,"compositeScore":16,"rankGlobal":10,"rankLanguage":10,"license":17,"archived":18,"fork":18,"defaultBranch":19,"hasWiki":20,"hasPages":18,"topics":21,"createdAt":10,"pushedAt":10,"updatedAt":22,"readmeContent":23,"aiSummary":24,"trendingCount":15,"starSnapshotCount":15,"syncStatus":25,"lastSyncTime":26,"discoverSource":27},1966,"CastFlow","yunzeforbetter\u002FCastFlow","yunzeforbetter","一套可移植的 AI 辅助开发框架。从项目代码中提取架构知识，生成结构化的 Skill 体系，并通过执行记录自动积累经验，让 AI 助手从第一天就深度理解你的项目，且越用越好。","",null,"Python",109,6,141,0,2.54,"MIT License",false,"main",true,[],"2026-06-12 02:00:35","# CastFlow\n\n> **让 AI 助手从第一天就深度理解你的项目，并且越用越懂。**\n\nCastFlow 是一套可移植、可演进、零成本采集的 **AI 协同开发操作系统**。它把\"AI 助手不理解项目\"这个行业难题，拆解成 **冷启动装架 → 渐进式信息披露 → 多模块编排 → 自我进化** 四层闭环，全部由项目真实代码驱动，不依赖任何大模型供应商、不占用任何运行时 token。\n\n一次装架，终身进化。\n\n---\n\n## 目录\n\n- [解决什么问题](#解决什么问题)\n- [核心设计理念](#核心设计理念)\n- [项目结构总览](#项目结构总览)\n- [端到端案例：从集成到自主进化](#端到端案例从集成到自主进化)\n- [文件清单（每个文件的作用）](#文件清单每个文件的作用)\n- [渐进式信息披露（T1-T4）](#渐进式信息披露t1-t4)\n- [自我进化详解](#自我进化详解)\n- [命令参考](#命令参考)\n- [升级与回滚](#升级与回滚)\n- [测试套件](#测试套件)\n\n---\n\n## 解决什么问题\n\nAI 助手进入大型项目常见的四种失控：\n\n| 问题 | 症状 | CastFlow 的治法 |\n|------|------|----------------|\n| 架构遗忘 | 生成的代码风格不一致、越过分层、绕过 Manager | `architect-skill` 从真实代码提取分层规则，T1-PREPARE 时点强制加载 |\n| API 幻觉 | 调用了不存在的方法、方法签名错乱、编译不通过 | P0 规则：EXAMPLES.md → 用户指导 → Grep 至少两次真实使用，均未命中则 TODO |\n| 知识碎片化 | 规则散落在口头约定、PR 评论、隐藏文档里，跨会话无法共享 | 四件套 Skill（SKILL\u002FEXAMPLES\u002FSKILL_MEMORY\u002FITERATION_GUIDE），文件即知识 |\n| 经验不积累 | 上一次犯过的错，下一次照犯不误 | Hook 零 token 采集编辑 trace → 八维评分筛选（含修正\u002F返工\u002F用户规则高权重维度）→ `origin-evolve-skill` 生成规则提议 → 用户审批写入 Skill |\n\n它是一套 **把项目知识变成可执行、可验证、可迭代的代码资产** 的AI工程框架。\n\n---\n\n## 核心设计理念\n\n### 1. 冷启动即可用：装架与生产解耦\n\n`python .castflow\u002Fbootstrap.py` 只做一件事 —— **装架**（Phase A）：把核心协议、元规范、模板、Hook、agent 定义同步到 `.claude\u002F`，生成项目根 `CLAUDE.md`。**不生成任何项目级 Skill 正文**。\n\n项目级 Skill（architect \u002F debug \u002F profiler \u002F programmer-\\\u003C模块\\>）由 **bootstrap-skill** 作为 AI skill 驱动，经 **子代理并行 + `skill-creator` 主路径** 按需生成。这样：\n\n- 安装器保持确定性（纯 Python，零依赖，可重入，`--dry-run` 可预览）\n- 内容生产保持创造性（AI 扫描真实代码，由 `AUTHORING_GUIDE.md` 约束产出质量）\n- 两者在 `SKILL_ITERATION.md` 元规范下同频\n\n### 2. 渐进式信息披露：时点驱动加载\n\nSkill 内容不会在每次调用时全量入上下文。按 **T1-PREPARE \u002F T2-EXECUTE \u002F T3-FEEDBACK \u002F T4-MAINTAIN** 四个行为时点分层加载：写代码前读一份、生成中按需补一份、反馈时记一份、迭代 skill 时另读一份。命名与映射的权威源是项目根 `CLAUDE.md`。\n\n### 3. 多模块编排：code-pipeline 工序流\n\n`code_pipeline 实现 X` 触发 **9 步**标准流水：**Step 1** 需求拆分与 API 声明（`requirement-analysis-agent`）→ **Step 2** 约束同步与 Handoff 冻结（同 agent，按需）→ **Step 3** 各模块实现（**模块配对执行单元**：`programmer-\u003Cmodule>-agent` + 同模块 skill）→ **Step 4** 依赖闭合（`integration-matching-agent`）→ **Step 5** 覆盖验收与 verdict（`pipeline-verify-agent`）→ **Step 6** 补全 `CompletableBlocks`（按需）→ **Step 7\u002F8** 调试与性能（可选）→ **Step 9** 收尾与 `pipeline_run_id` 清理。编排合同与 Step 调度卡见装架产物 `skills\u002Fcode-pipeline-skill\u002Fconfig\u002Fpipeline_protocol.md`；AI 入口见同目录 `SKILL.md`。\n\n### 4. 自我进化：零 token 采集 + 八维评分 + 经验记录 + 人在回路\n\nHook 每次编辑时自动记录 `path|lines|edits|flags`（修正检测用 `SequenceMatcher.ratio()` 对比前后编辑，相似度 > 60% 打 R 标）。会话结束跑八维评分：\n\n```\nscore = F·1.0 + D·0.5 + K·1.5 + S·0.5 + E·0.8 + C·2.0 + R·2.5 + U·2.0\n```\n\n前 5 维（F\u002FD\u002FK\u002FS\u002FE）**衡量改动规模**\n后 3 维（C\u002FR\u002FU）衡量**学习价值**：\n\n\n**高价值绕过**：C\u002FR\u002FU 任一非零时，无论总分是否达标都写入 trace——因为\"小改动但犯了错\"往往比\"大改动一帆风顺\"更值得记录。\n\nTrace 输出聚焦经验信息：模块、评分、错误原因、修复方案、用户反馈、经验总结。`origin-evolve-skill` 读 trace、识别模式、生成 Append\u002FMerge\u002FRetire 提议，**用户审批后才写入** Skill。\n\n---\n\n## 项目结构总览\n\n```\nCastFlow\u002F\n├── README.md                              # 本文件\n├── CHANGELOG.md                           # 按版本变更记录\n├── LICENSE\n├── bootstrap-skill\u002F                       # 【顶层 AI skill】框架初始化器，\n│   │                                      # 由 \"bootstrap castflow\" 触发，驱动装架与 project skill 生成\n│   ├── SKILL.md                           #   Phase 0-6 工作流、语言门禁、模板路径\n│   ├── EXAMPLES.md                        #   Phase 0\u002F2\u002F3 对外话术、manifest 示例、核心更新对话\n│   ├── SKILL_MEMORY.md                    #   规则 1-9（语言门禁、占位符实值化、shell pipe 禁令等）\n│   └── ITERATION_GUIDE.md                 #   迭代本 skill 的规范\n│\n├── .castflow\u002F                             # 框架源码（装架后休眠，仅随 git pull 更新）\n│   ├── bootstrap.py                       # 薄包装器，委托到 installer\u002F\n│   │\n│   ├── installer\u002F                         # 装架引擎（纯 Python 3.6+，零依赖）\n│   │   ├── cli.py                         #   CLI 解析 + 主流程编排\n│   │   ├── paths.py                       #   项目根 \u002F harness 目录查找（支持 submodule 任意深度）\n│   │   ├── backup.py                      #   BackupSession 会话目录式备份 + LRU 轮换\n│   │   ├── io_ops.py                      #   safe_write \u002F safe_copy_file \u002F safe_copy_dir\n│   │   ├── templates.py                   #   {{PLACEHOLDER}} 替换 + conditional block\n│   │   ├── placeholders.py                #   各类占位符字典构建（已精简：安装器不再负责 skill 正文）\n│   │   ├── hook_config.py                 #   .cursor\u002Fhooks.json 与 .claude\u002Fsettings.json 幂等合并\n│   │   ├── claude_merge.py                #   CLAUDE.md 三策略合并（1=换模板 \u002F 2=保留 \u002F 3=增量）\n│   │   ├── validate.py                    #   Skill 规范验证（无 emoji \u002F 无日期 \u002F 无残留占位符 \u002F 字数）\n│   │   ├── manifest.py                    #   bootstrap-output\u002Fcf_manifest.json 读写\n│   │   └── generate.py                    #   Phase A 全量 + Phase A 子集（--claude-md-only \u002F --templates-only）\n│   │\n│   ├── core\u002F                              # 被装架同步到 .claude\u002F 的核心内容\n│   │   ├── CLAUDE.template.md             #   项目根 CLAUDE.md 的框架段模板（时点定义唯一权威源）\n│   │   ├── GLOBAL_SKILL_MEMORY.md         #   跨 skill 运行时协议 1\u002F2\u002F3\n│   │   ├── SKILL_ITERATION.md             #   Skill 四文件元规范 + Anchors 格式 + 容量治理\n│   │   ├── protocols\u002F\n│   │   │   ├── idp-protocol.md            #   Intent Declaration Protocol（T2 按需）\n│   │   │   └── validated-protocol.md      #   接受\u002F拒绝信号判定（T3）\n│   │   ├── skills\u002F                        # 3 个核心 skill（随装架拷贝到 .claude\u002Fskills\u002F）\n│   │   │   ├── code-pipeline-skill\u002F       #   多模块协作 9 步工序 + pipeline_protocol\n│   │   │   │   └── scripts\u002F\n│   │   │   │       └── pipeline_merge.py  #     pipeline Step 3 并行输出聚合\n│   │   │   ├── origin-evolve-skill\u002F       #   读 trace、识别模式、生成 Append\u002FMerge\u002FRetire 提议\n│   │   │   └── skill-creator\u002F             #   Skill 生成\u002F迭代\u002Feval\u002Fbenchmark 全套工具链\n│   │   ├── agents\u002F                        # code-pipeline 调用的 3 个分析型 agent prompt\n│   │   │   ├── requirement-analysis-agent.md\n│   │   │   ├── integration-matching-agent.md\n│   │   │   └── pipeline-verify-agent.md\n│   │   ├── hooks\u002F                         # 生产 Hook 脚本（跨平台）\n│   │   │   ├── trace-collector.py         #   编辑事件采集 + 自我修正检测（LRU 50 文件快照）\n│   │   │   └── trace-flush.py             #   会话结束 → 五维评分 → trace.md + 四级 compaction\n│   │   ├── templates\u002F                     # 装架后供 skill-creator 使用的创作资产\n│   │   │   ├── AUTHORING_GUIDE.md         #   Skill 创作元规范（四份域 README 的共享上游）\n│   │   │   ├── agents\u002Fprogrammer.template.md\n│   │   │   └── skills\u002Fprogrammer.template\u002F   # 模块 skill 四件套模板 + 域 README\n│   │   └── traces\u002F                        # 默认阈值与字段契约（分发到 .claude\u002Ftraces\u002F）\n│   │       ├── config\u002F\n│   │       │   ├── limits.json            #   compaction 阈值 \u002F 过期天数 \u002F 保护参数\n│   │       │   └── hooks.config.json      #   追踪扩展名 \u002F 通用目录段 \u002F 模块推断正则（跨语言适配入口）\n│   │       └── README.md                  #   trace 字段契约 + limits \u002F hooks.config 说明\n│   │\n│   └── bootstrap-assets\u002F                  # 仅在冷启动期间使用的资产（不进 .claude\u002F）\n│       └── skill-templates\u002F               #   architect \u002F debug \u002F profiler 的四件套模板 + 域 README\n│           ├── architect.template\u002F\n│           ├── debug.template\u002F\n│           └── profiler.template\u002F\n│\n└── test\u002F                                  # 框架自身回归测试（不被 bootstrap 分发，176+ tests）\n    ├── hooks\u002F                             # 134 tests：评分、compaction、100 天 \u002F 365 天模拟\n    ├── bootstrap\u002F                         # 42 tests：installer 包单元测试\n    └── origin-evolve\u002F                     # ~7000 次断言：origin-evolve 规范暴力验证\n```\n\n### 装架后用户项目的结构\n\n```\n项目根目录\u002F\n├── CLAUDE.md                              # 项目全局规则（框架段 + 项目段，增量合并）\n├── .claude\u002F\n│   ├── skills\u002F\n│   │   ├── GLOBAL_SKILL_MEMORY.md         # T1\u002FT2 运行时协议\n│   │   ├── SKILL_ITERATION.md             # Skill 四文件元规范\n│   │   ├── code-pipeline-skill\u002F           # 【核心】多模块工序\n│   │   ├── origin-evolve-skill\u002F           # 【核心】自我进化引擎\n│   │   ├── skill-creator\u002F                 # 【核心】Skill 生成工具（含 eval\u002Fbenchmark）\n│   │   ├── architect-skill\u002F               # 【项目级，Phase 5 生成】\n│   │   ├── debug-skill\u002F                   # 【可选，Phase 2 勾选才生成】\n│   │   ├── profiler-skill\u002F                # 【可选，Phase 2 勾选才生成】\n│   │   └── programmer-\u003C模块>-skill\u002F       # 【按需生成】\n│   ├── protocols\u002F                         # idp \u002F validated 两份按需协议\n│   ├── agents\u002F                            # code-pipeline 调用的 3 个分析 agent\n│   ├── hooks\u002F                             # trace-collector.py + trace-flush.py\n│   ├── templates\u002F                         # AUTHORING_GUIDE + programmer.template + agent 模板\n│   ├── traces\u002F                            # trace.md \u002F weights.json \u002F config\u002Flimits.json \u002F config\u002Fhooks.config.json\n│   ├── rules\u002F                             # origin-evolve 生成的跨模块规则\n│   └── settings.json                      # Claude Code hook 配置（增量合并）\n├── .cursor\u002F\n│   └── hooks.json                         # Cursor hook 配置（增量合并）\n└── CastFlow\u002F                              # 框架源码（submodule，进入休眠）\n```\n\n---\n\n## 端到端案例：从集成到自主进化\n\n### 步骤 1 — 集成（30 秒）\n\n```bash\ngit submodule add https:\u002F\u002Fgithub.com\u002Fyunzeforbetter\u002FCastFlow.git\n```\n\n**CastFlow 最好放置在与.claude目录同级的位置**\n\n### 步骤 2 — 冷启动（约 5 分钟，AI 主导）\n\n在 Cursor \u002F Claude Code 中输入：\n\n```\nbootstrap castflow\n```\n\nAI 加载 `CastFlow\u002Fbootstrap-skill\u002FSKILL.md` 并按 Phase 0-6 执行：\n\n| Phase | 动作 | 结果 |\n|-------|------|------|\n| 0 | **语言门禁** — 输出 zh\u002Fen\u002Fja\u002Fko\u002Fother 菜单，等用户回复 | `manifest.language = zh` |\n| 1 | 扫描 `Assets\u002FScripts\u002F`、Unity 版本、命名约定 | 内部知识 |\n| 2 | 询问 **debug \u002F profiler** 是否启用（单独消息） | `optional_skills` |\n| 3 | 确认命名规范（单独消息，可补充团队约定） | `content\u002Fclaude\u002Fnaming_conventions.md` |\n| 4 | **装架** — `python .castflow\u002Fbootstrap.py`（**Phase A**：.claude\u002F 核心 + 根 CLAUDE.md + templates\u002F） | `.claude\u002F` 就绪 |\n| 5 | **Phase 5 子代理并行**：主 agent 对每个项目级 skill 发一段话（任务 + 必读 `SKILL_ITERATION.md` + `AUTHORING_GUIDE.md` + 域 README + 模板 + 占位符实值 + 语言），子代理用 **skill-creator** 扫描真实代码、填模板、落盘到 `.claude\u002Fskills\u002F\u003Cname>\u002F` | `architect-skill\u002F`（+ 可选 `debug-skill\u002F` \u002F `profiler-skill\u002F`） |\n| 6 | `python .castflow\u002Fbootstrap.py --validate` 校验规范，清理 `bootstrap-output\u002F` | 冷启动完成 |\n\n此时项目已拥有完整的 Skill 骨架 + Hook 配置。`.cursor\u002Fhooks.json` 与 `.claude\u002Fsettings.json` 已增量合并，Hook 开始静默采集。\n\n**如果出现搜寻不到的情况，可以显示告诉ai助手CastFlow的完整路径并让它启用 bootstrap castflow**\n\n### 步骤 3 — 为xx模块生成 Skill（按需增量）\n\n```\n为xx系统生成 skill\n```\n\n触发 `skill-creator`（不需要记忆命令，自然语言即可）：AI 会自动完成代码扫描、信息提炼、四文件生成。**这是项目知识体系持续扩张的主要渠道**。\n\n### 步骤 4 — 日常使用：Skill + Pipeline\n\n**单 skill 调用**（自然语言描述匹配元数据自动加载）：\n\n```\n帮我在xx系统里加一个批量升级功能\n```\n\n**多模块编排**：\n\n```\ncode_pipeline 实现用户交易系统\n```\n\n触发 9 步工序：需求分析 agent 拆模块与 API →（可选）约束冻结 → 各模块 **配对执行单元** 并行实现 → `pipeline_merge.py` 将 Step 3 摘要归并到 `PIPELINE_CONTEXT.md` → 集成匹配 agent 做依赖闭合 → `pipeline-verify-agent` 验收与 verdict →（按需）补全与重跑闭合 → 收尾。 **非常适合完整系统开发**\n\n### 步骤 5 — 自主进化（零干预采集，人在回路审批）\n\n一周后，`trace.md` 累积了 30 多条 pending 条目，其中 5 条含 `correction:auto:major` 标记（Hook 自动检测到的 AI 反复修正）。新会话打开时，`evolve-reminder` 规则静默检查并提示：\n\n```\n检测到 5 条 pending 条目含修正信号，建议运行: origin evolve\n```\n\n用户输入 `origin evolve`：\n\n1. 读 trace，`validated:false` P0、修正条目 P1\u002FP2 排序\n2. 识别六类模式（修正聚簇 \u002F 模块热点 \u002F 复杂度集中 \u002F 跨 skill 锚点重叠 \u002F 知识缺口 \u002F IDP 缺失）\n3. 生成提议：\n   - **Append** 一条 `programmer-xxx-skill\u002FSKILL_MEMORY.md` 规则：*批量升级必须复用 `xxxx`，禁止直接调 `xx`*，Anchors = `[class:xx, method:xxx]`\n   - **Retire** 一条旧规则（grep 验证其 Anchors 在代码中已不存在）\n   - **Merge** 两条锚点 Jaccard ≥ 0.5 的重复规则\n4. 用户逐个审批（可拒绝，拒绝会记录 `EVOLVE_REJECTION` 避免重复提议）\n5. 写入，原 trace 条目替换为一行 `\u003C!-- PROCESSED ts:... entries:N proposals:M -->`\n6. 可选：对比有效\u002F无效 trace 的 F\u002FD\u002FK\u002FS\u002FE 分布，单维度权重微调 5-10% 写入 `weights.json`\n\n下次会话：新规则 + 校准后的评分模型同时生效。AI 不再重复犯这一类错。\n\n### 步骤 6 — 框架升级\n\n```bash\ncd CastFlow && git pull\n```\n\n然后在 AI 中再次输入 `bootstrap castflow`，它会走 **核心更新** 工作流：复用 `manifest.language`，对比 `.castflow\u002Fcore\u002F` 与项目 `.claude\u002F` 差异，仅更新元规范、核心 skill、protocols、templates，**项目级 skill 与 CLAUDE.md 项目段完全保留**。\n\n---\n\n## 文件清单（每个文件的作用）\n\n### `CastFlow\u002Fbootstrap-skill\u002F` — 顶层 AI skill（框架初始化器）\n\n与其他 skill 的区别：它在 **.claude\u002F 尚未存在** 时就要运行，因此驻留在 CastFlow 源码内，由用户在 AI 助手中通过自然语言触发。\n\n| 文件 | 作用 |\n|------|------|\n| `SKILL.md` | Phase 0-6 工作流定义、两种工作流（全量初始化 \u002F 核心更新）、Phase 5 一段话手话规范与占位符表 |\n| `EXAMPLES.md` | Phase 0\u002F2\u002F3 对外话术模板、`cf_manifest.json` 字段示例、模块 skill 对话范例 |\n| `SKILL_MEMORY.md` | 9 条硬性规则：语言门禁、manifest 识别、占位符必须实值化、禁止 shell pipe 写文件等 |\n| `ITERATION_GUIDE.md` | 本 skill 自身的演进规则 |\n\n### `.castflow\u002Fbootstrap.py` + `installer\u002F` — 装架引擎\n\n`bootstrap.py` 是薄包装器。真实实现全在 `installer\u002F` 包（11 个模块），所有 I\u002FO 可 `--dry-run`、可备份、可 `--validate`。\n\n| 模块 | 作用 |\n|------|------|\n| `cli.py` | 参数解析 + 主流程调度。支持 `--claude-md-only` \u002F `--templates-only` \u002F `--agent` \u002F `--init-manifest` \u002F `--language` \u002F `--claude-md-harness`（三策略）\u002F `--project-root` \u002F `--no-backup` \u002F `--backup-keep` \u002F `--clean-backups` |\n| `paths.py` | 双路径解耦：`find_project_root` 向上查 `.claude\u002F`（首次初始化时自动创建）；`find_harness_dir` 锚定 `.castflow\u002F` 本体 |\n| `backup.py` | `BackupSession` 会话目录备份（`.claude\u002F.backups\u002F\u003Ctimestamp>\u002F`），LRU 保留 N 次（默认 3），自动清理旧 `.bak` 散文件，自动追加 `.gitignore` 条目 |\n| `io_ops.py` | 三件套写入：`safe_write` \u002F `safe_copy_file` \u002F `safe_copy_dir`。统一带 `merge_mode` + `dry_run` + `backup` |\n| `templates.py` | `{{PLACEHOLDER}}` 替换（`strict=True` 未知 key 直接 fail）+ `\u003C!-- if:tech -->` 条件块处理 |\n| `placeholders.py` | 精简后仅构建 CLAUDE.md \u002F agent 所需占位符字典；不再构建 architect\u002Fdebug\u002Fprofiler\u002Fprogrammer 的 skill 内容占位符（这些改由 skill-creator 子代理负责） |\n| `hook_config.py` | Cursor `hooks.json` 与 Claude Code `settings.json` 的幂等增量合并，不覆盖项目已有 hook |\n| `claude_merge.py` | CLAUDE.md 三策略：1=整段换模板（旧段备份）\u002F 2=保留当前 \u002F 3=增量合并（模板新段 + 把项目段多出来的行追加进来）。非 TTY 默认 3，TTY 交互提示 |\n| `validate.py` | Skill 规范验证：无 emoji、无日期、无残留 `{{KEY}}`、字数预算（代码块除外） |\n| `manifest.py` | `bootstrap-output\u002Fcf_manifest.json`（canonical 名）读写 + 迁移老版 `manifest.json` 提示 |\n| `generate.py` | `generate_all`（Phase A 全量）+ `run_phase_a_subset`（--claude-md-only \u002F --templates-only）+ `generate_agent`（`--agent \u003Cmodule>`） |\n\n### `.castflow\u002Fcore\u002F` — 被同步到 `.claude\u002F` 的框架内容\n\n| 文件\u002F目录 | 作用 |\n|-----------|------|\n| `CLAUDE.template.md` | 项目根 `CLAUDE.md` 的框架段模板。**时点定义（T1-T4）的唯一权威源** |\n| `GLOBAL_SKILL_MEMORY.md` | 跨 skill 运行时协议：协议 1（API 物理验证）、协议 2（学习后约束对齐）、协议 3（执行模式检测） |\n| `SKILL_ITERATION.md` | Skill 四文件元规范：各文件职责隔离、Anchors\u002FRelated 格式、容量治理阈值、硬性约束清单 |\n| `protocols\u002Fidp-protocol.md` | Intent Declaration Protocol 写入规则（T2-EXECUTE 按需） |\n| `protocols\u002Fvalidated-protocol.md` | 用户接受\u002F拒绝信号判定与写入规则（T3-FEEDBACK） |\n| `skills\u002Fcode-pipeline-skill\u002F` | 多模块协作 9 步工序（复合组件）。含 `SKILL.md`（工作流总览）、`config\u002Fpipeline_protocol.md`（含 Step 调度卡）、`config\u002Fhandoff_protocol.md`、`architecture\u002F*.md`（复杂系统）、`EXAMPLES.md` + `examples\u002F*`、`scripts\u002Fpipeline_merge.py`、`config\u002Fdefaults.json` + `config\u002Fparams.schema.json` |\n| `skills\u002Forigin-evolve-skill\u002F` | 自我进化引擎。读 trace、识别六类模式、生成 Append\u002FMerge\u002FRetire 提议，走用户审批 |\n| `skills\u002Fskill-creator\u002F` | Skill 生成与迭代工具链。含 `agents\u002F{analyzer,comparator,grader}.md`、`scripts\u002F` 7 个工具（eval 运行、benchmark 聚合、打包、描述优化等）、`eval-viewer\u002F`、`references\u002Fschemas.md` |\n| `agents\u002Frequirement-analysis-agent.md` | Pipeline **Step 1 \u002F Step 2**：需求拆分、API 声明、（可选）约束同步与蓝图冻结 |\n| `agents\u002Fintegration-matching-agent.md` | Pipeline **Step 4**：依赖闭合验证（Dependency Closure Report） |\n| `agents\u002Fpipeline-verify-agent.md` | Pipeline **Step 5**：Done Criteria 与 Module\u002FGlobal Verdict、result signal |\n| `hooks\u002Ftrace-collector.py` | 每次文件编辑被调用。记录路径\u002F行数\u002F编辑次数；保存 `new_string` 快照（LRU 50）；用 `SequenceMatcher.ratio()` 检测 AI 自我修正标记 `R`；`tracked_extensions` \u002F `excluded_extensions` 从 `traces\u002Fconfig\u002Fhooks.config.json` 加载 |\n| `hooks\u002Ftrace-flush.py` | 会话结束被调用。读 buffer → 八维评分 F\u002FD\u002FK\u002FS\u002FE\u002FC\u002FR\u002FU → 达标或高价值绕过写入 `trace.md`（含经验字段：error_cause\u002Ffix_approach\u002Fuser_feedback\u002Flesson）→ 四级 compaction → validated 条目受保护。含 `--selftest` 子命令 |\n| `templates\u002FAUTHORING_GUIDE.md` | Skill 创作元规范（四份域 README 的共享上游）。包含项目勘察清单、反风格检查、Rubric |\n| `templates\u002Fagents\u002Fprogrammer.template.md` | 为功能模块生成专属 programmer agent 时的 prompt 模板 |\n| `templates\u002Fskills\u002Fprogrammer.template\u002F` | 模块 skill 四件套模板 + 域 README（最常用，会被分发到 `.claude\u002Ftemplates\u002F`） |\n| `skills\u002Fcode-pipeline-skill\u002Fscripts\u002Fpipeline_merge.py` | code-pipeline **Step 3** 调用：从各模块 `temp\u002Fpipeline-output\u002F*.md` 提取 `PIPELINE_SUMMARY`，写入 `PIPELINE_CONTEXT.md` 内受控归并块（幂等替换）；缺标记或混入 `Parent Summary` 时 fail-closed |\n| `traces\u002Fconfig\u002Flimits.json` | compaction 阈值、过期天数、保护参数的运行时默认值 |\n| `traces\u002Fconfig\u002Fhooks.config.json` | Hook 外部化配置：`tracked_extensions`（18 种主流语言）、`excluded_extensions`、`generic_dir_segments`、`module_dir_pattern`。**修改此文件即可适配非 Unity\u002FC# 项目，无需改 Python** |\n| `traces\u002FREADME.md` | trace 字段契约 + `schema:N` 版本规则 + limits\u002Fhooks.config 全字段说明 + Go\u002FReact 适配示例 |\n\n### `.castflow\u002Fbootstrap-assets\u002F` — 仅冷启动使用\n\n`skill-templates\u002F{architect,debug,profiler}.template\u002F` 各含四份 `*.template.md` + 一份 `README.md`（域说明）。这些模板 **不被安装器分发到 `.claude\u002F`**，由 Phase 5 的子代理在执行 `skill-creator` 时直接读取填充。\n\n### `test\u002F` — 框架自身回归测试（不分发）\n\n| 文件 | 覆盖 | 规模 |\n|------|------|------|\n| `hooks\u002Ftest_evolution.py` | collector 采集、buffer 格式、flush 评分、compaction 四级、validated 保护、审计行过期、空行清理 | 84 tests |\n| `hooks\u002Ftest_100day_simulation.py` | 100 天持续 append+compact 有界性、模块多样性 | 27 tests |\n| `hooks\u002Ftest_365day_simulation.py` | 365 天生产模拟：工作日\u002F周末、季度漂移、混合会话、知识库生命周期 | 23 tests |\n| `bootstrap\u002Ftest_bootstrap.py` | installer 包：占位符替换、strict 模式、CLAUDE.md 三策略、hook config 幂等合并、BackupSession、LRU 轮换 | 42 tests |\n| `origin-evolve\u002Fverify_redesign.py` | origin-evolve 规范确定性部分暴力验证：诊断计数、归因树、Append\u002FMerge\u002FRetire、Jaccard 边界、容量策略 | ~7000 次断言 |\n\n---\n\n## 渐进式信息披露（T1-T4）\n\n命名约定 `T\u003C序号>-\u003C动词>`，权威源为项目根 `CLAUDE.md`「使用Skill的分层加载」段（always-applied，自动注入）。\n\n| 时点 | 触发 | AI 主动读什么 |\n|------|------|--------------|\n| **T1-PREPARE** | 写代码前 | `GLOBAL_SKILL_MEMORY.md` 协议 1\u002F2 + 目标 skill 的 `SKILL_MEMORY.md` + 按需 `EXAMPLES.md` 章节 |\n| **T2-EXECUTE** | 代码生成中 | `GLOBAL_SKILL_MEMORY.md` 协议 3 + 按需 `protocols\u002Fidp-protocol.md` |\n| **T3-FEEDBACK** | 用户反馈 | `protocols\u002Fvalidated-protocol.md` |\n| **T4-MAINTAIN** | 创建\u002F修改 skill 结构 | `SKILL_ITERATION.md` + 目标 skill 的 `ITERATION_GUIDE.md` |\n\n时点不强制串行。四文件职责隔离是硬约束：代码示例只放 EXAMPLES、硬性规则只放 SKILL_MEMORY、导航和定位放 SKILL、演进规则放 ITERATION_GUIDE。\n\n---\n\n## 自我进化详解\n\n### 两层数据采集（Hook 零 token + AI 经验填充）\n\n```\n编辑文件 → trace-collector 记录 path|lines|edits|flags → buffer\n会话结束 → trace-flush 读 buffer → 八维评分 → 达标或高价值绕过写 trace.md\nAI (IDP) → 填充经验字段：error_cause \u002F fix_approach \u002F user_feedback \u002F lesson\n```\n\n| 平台 | 配置文件 | 编辑事件 | 结束事件 |\n|------|---------|---------|---------|\n| Cursor | `.cursor\u002Fhooks.json` | `afterFileEdit` | `stop` |\n| Claude Code | `.claude\u002Fsettings.json` | `PostToolUse(Write)` | `Stop` |\n\n### 八维评分模型\n\n```\nscore = F·1.0 + D·0.5 + K·1.5 + S·0.5 + E·0.8 + C·2.0 + R·2.5 + U·2.0    准入 score ≥ 1.5 或 C\u002FR\u002FU 非零\n```\n\n| 维度 | 含义 | 计算 | 权重 | 价值 |\n|------|------|------|------|------|\n| F — File Count | 修改文件数 | `min(files\u002F3, 1.0)` | 1.0 | 多文件 = 更值得记录 |\n| D — Module Spread | 模块分散度 | `min(modules\u002F2, 1.0)` | 0.5 | 跨模块 = 架构决策 |\n| K — Critical Path | 关键路径等级 | 接口 1.0 \u002F 实现 0.6 \u002F 基础 0.3 | 1.5 | 架构影响力梯度 |\n| S — Change Scale | 改动规模 | `min(lines\u002F50, 1.0)` | 0.5 | 大改更可能有价值 |\n| E — Edit Intensity | 编辑密度 | `min(edits\u002F5, 1.0)` | 0.8 | 反复修改 = 困难迭代 |\n| C — Correction | 自我修正 | revert≥3→1.0, ≥1→0.6 | 2.0 | 模型犯错并改正 = 高学习价值 |\n| R — Rework | 用户返工 | mode=rework→1.0 | 2.5 | 用户拒绝 = 最高学习价值 |\n| U — User-Rule | 用户规则 | mode=user-rule→1.0 | 2.0 | 强制约束 = 必须记住 |\n\n**高价值绕过**：C\u002FR\u002FU 任一非零直接写入 trace，不受阈值限制。确保\"小改动大教训\"不被丢弃。\n\n### Trace 条目结构\n\n```\n\u003C!-- TRACE status:pending schema:2 -->\ntimestamp: 2026-05-12T12:58:55Z\nmode: rework\ntype: bugfix\nmodules: [Building]\nskills: [programmer-ui-skill]\nscore: 4.84\nscore_breakdown: F=0.33 D=0.25 S=0.08 E=0.48 C=1.2 R=2.5\ncorrection: auto:minor\nvalidated: _\npipeline_run_id: _\nerror_cause: ObservableList.Add always appends, used it for ordered insert\nfix_approach: Changed to Insert(index, item) with bounds check\nuser_feedback: 不行，列表顺序不对，必须插入到指定位置\nlesson: ObservableList ordered insert must use Insert(index) not Add()\n\u003C!-- \u002FTRACE -->\n```\n\n`status`：`pending` → `processed` \u002F `expired` \u002F `invalid`\n`validated`：`_` \u002F `true` \u002F `false`（P0） \u002F `pending-pipeline` \u002F `invalid`\n`correction`：`_` \u002F `auto:minor` \u002F `auto:major`\n\n### 四级 Compaction\n\n| 级 | 触发 | 策略 | 保护 |\n|----|------|------|------|\n| L0 | 每次 flush | 清理过期 PROCESSED\u002FCOMPACTED 审计行 | — |\n| L1 | entries > `compact_max_entries` | 移除超过 `entry_expire_days` 的低分 | `validated` 条目 |\n| L2 | L1 后仍超标 | 移除 `age > level2_age_days` 且 `score \u003C level2_score_threshold` | `validated` 条目 |\n| L3 | L2 后仍超标 | 移除 `score \u003C level3_score_threshold` | 每模块保留 top N（`keep_top_n_per_module`） |\n\n`validated` 条目（`true` \u002F `false` \u002F `pending-pipeline`）携带用户反馈信号，**L1-L3 全部受保护**。\n\n### origin-evolve 执行流\n\nevolve-reminder 规则检测到 `pending ≥ 5` 或含修正信号的条目 `≥ 3` 时提醒用户。`origin-evolve-skill` 永远不会自动执行。\n\n```\nStep 1 Read & Triage（schema 门控 + 诊断计数 + P0-P4 排序 + `.trace_lock`）\nStep 2 Identify Patterns（六类模式，要求 3+ 证据）\nStep 3 Generate Proposals（归属决策树 + Append\u002FMerge\u002FRetire + 容量检查 + Anchors grep 验证）\nStep 4 User Approval（逐个，可拒绝并记录 EVOLVE_REJECTION）\nStep 5 Write & Mark Processed（原子写 + 审计行替换）\nStep 6 Calibrate（可选，单维度 5-10% 微调 weights.json）\n```\n\n**Anchors 精确格式**：`[kind:path-hint:symbol]`，`kind ∈ {class, method, field, api, pattern}`。\n示例：`[class:Building\u002FBuildingManager, method:Building\u002FBuildingFunc:OnUpgrade, pattern:EventArgs.Create]`。旧格式 `[BuildingManager, OnUpgrade]` 仍向后兼容。\n\n### 自校准闭环\n\n```\n编辑 → 采集 → 八维评分 → trace (pending, 含经验字段)\n       ↓\n提醒 → origin evolve → 模式识别 → 提议 → 审批 → 写入 Skill\n                                         ↓\n                                   校准 weights.json（可选）\n                                         ↓\n                                   下次会话：新知识 + 优化模型\n```\n\n---\n\n## 命令参考\n\n### AI 触发词（日常使用）\n\n| 触发词 | 动作 |\n|--------|------|\n| `bootstrap castflow` | 首次初始化 \u002F 核心更新（由 bootstrap-skill 分流） |\n| `为 X 系统生成 skill` \u002F `分析 Assets\u002FScripts\u002FX\u002F 为这个模块创建 skill` | 触发 skill-creator 生成功能模块 skill |\n| `帮我创建一个 X 的 skill` | 触发 skill-creator 生成自由格式 skill |\n| `code_pipeline 实现 X` | 触发多模块 9 步工序 |\n| `origin evolve` | 运行自我进化分析 |\n\n### `bootstrap.py` CLI\n\n```bash\npython .castflow\u002Fbootstrap.py                      # Phase A 全量装架\npython .castflow\u002Fbootstrap.py --dry-run            # 预览，不写入\npython .castflow\u002Fbootstrap.py --validate           # 验证 .claude\u002Fskills\u002F 规范\npython .castflow\u002Fbootstrap.py --claude-md-only     # 仅更新根 CLAUDE.md\npython .castflow\u002Fbootstrap.py --templates-only     # 仅刷新 .claude\u002Ftemplates\u002F\npython .castflow\u002Fbootstrap.py --agent \u003Cmodule>     # 增量生成 programmer-\u003Cmodule>-agent\npython .castflow\u002Fbootstrap.py --project-root \u002Fpath # 显式指定项目根\npython .castflow\u002Fbootstrap.py --claude-md-harness 3  # CLAUDE.md 合并策略（1\u002F2\u002F3）\npython .castflow\u002Fbootstrap.py --init-manifest --language zh  # 非交互生成缺省 manifest\npython .castflow\u002Fbootstrap.py --no-backup          # 跳过备份（git 用户）\npython .castflow\u002Fbootstrap.py --backup-keep 5      # 保留最近 5 次备份\npython .castflow\u002Fbootstrap.py --clean-backups      # 清空所有备份并退出\n\n# Hook 独立健康检查（不依赖真实 hook 事件）\npython .claude\u002Fhooks\u002Ftrace-flush.py --selftest\n```\n**如果出现python指令无效果，观察是不是未配置环境变量，或者直接使用py -3 来替代**\n\nCLI 的关键移除：\n- **移除 `--skill`**：易与\"生成 skill\"混淆；Phase 5 项目级 skill 改走子代理 + skill-creator\n- **移除 `--strict-content`**：安装器不再做内容合并，无需此开关\n- **移除 Phase B**：`generate_all` 只跑 Phase A\n\n### 文件归属速查\n\n| 分类 | 管理方 | 更新方式 |\n|------|--------|---------|\n| `CastFlow\u002F` | CastFlow 仓库 | `git pull` \u002F submodule update |\n| `CLAUDE.md` 框架段 | bootstrap | 装架时合并（三策略） |\n| `CLAUDE.md` 项目段 | 项目团队 | 直接编辑 |\n| `.claude\u002Fskills\u002F*` 核心 skill | CastFlow 框架 | 装架同步 |\n| `.claude\u002Fskills\u002F*` 项目 skill | 项目团队 + 进化系统 | skill-creator 创建 \u002F origin-evolve 追加 |\n| `.claude\u002Fhooks\u002F` | CastFlow 框架 | 装架生成 |\n| `.claude\u002Ftraces\u002F` | Hook + evolve | 不手动编辑 |\n| `.claude\u002Frules\u002F` | 进化系统 | evolve 提议，用户审批后生成 |\n\n不要手动编辑 `CastFlow\u002F.castflow\u002F`（会被 `git pull` 覆盖）。所有定制在 `.claude\u002F` 与 `CLAUDE.md` 项目段完成。\n\n---\n\n## 升级与回滚\n\n```bash\ncd CastFlow && git pull\n# 然后在 AI 中输入 bootstrap castflow（会走核心更新工作流）\n```\n\n**备份机制**：`merge_mode: full` 覆盖任意已有文件前，原件复制到会话目录：\n\n```\n.claude\u002F.backups\u002F\u003CYYYY-MM-DD_HH-MM-SS>\u002F\n    .claude\u002F\n        agents\u002Frequirement-analysis-agent.md\n        skills\u002Fcode-pipeline-skill\u002F...\n```\n\n保留原始相对路径结构，回滚直接 `robocopy` \u002F `rsync` 拷回即可。默认保留最近 3 次会话，更早自动删除。首次使用新版会一次性清理旧版散落的 `.bak` 文件并追加 `.backups\u002F` 到 `.claude\u002F.gitignore`。\n\n---\n\n## 测试套件\n\n所有测试集中在 `CastFlow\u002Ftest\u002F`（与 `.castflow\u002F` 同级，**不被 bootstrap 分发**），零外部依赖（仅 `unittest`）。每次运行在临时目录创建隔离环境，不影响项目数据。\n\n```bash\n# Hook 流水线（134 tests）\ncd CastFlow\u002Ftest\u002Fhooks\npy test_evolution.py\npy test_evolution.py --keep-data          # 保留到 test-output\u002Fevolution\u002F\npy test_100day_simulation.py --keep-data\npy test_365day_simulation.py --keep-data\npy -m unittest discover -s . -p \"test_*.py\"\n\n# installer 包（42 tests）\ncd CastFlow\u002Ftest\u002Fbootstrap\npy test_bootstrap.py\n\n# 全量（176 tests）\ncd CastFlow\npy -m unittest discover -s test -p \"test_*.py\"\n\n# origin-evolve 规范暴力验证（~7000 断言，~1 秒）\ncd CastFlow\u002Ftest\u002Forigin-evolve\npy verify_redesign.py\n\n# macOS \u002F Linux：将 py 替换为 python3\n```\n\n**测试覆盖层级**：\n\n| 层级 | 是否覆盖 | 说明 |\n|------|---------|------|\n| Python 函数正确性 | 是 | 评分公式、compaction 逻辑、状态转换等直接调用真实代码 |\n| 数据格式与流转 | 是 | trace 条目的写\u002F读\u002F解析\u002F压缩全链路用真实 `trace.md` 文件 |\n| Hook 事件触发 | 否 | Cursor\u002FClaude Code 通过 stdin JSON 触发 Hook，测试中直接调用函数替代 |\n| origin-evolve AI 分析 | 否 | 模式识别是 AI 行为，测试中用简化检测函数替代 |\n| 用户审批交互 | 否 | 人在回路无法自动化 |\n\n测试的使命是 **保证数据管道的机械正确性**：在长期持续写入和压缩下不会损坏、不会无限膨胀、不会丢失关键信号。AI 侧的质量由 Skill 元规范 + `validate.py` + 人在回路共同保障。\n\n---\n\n## LICENSE\n\n见 [LICENSE](.\u002FLICENSE)。\n","CastFlow 是一套可移植的 AI 辅助开发框架，旨在从项目代码中提取架构知识，生成结构化的 Skill 体系，并通过执行记录自动积累经验，让 AI 助手从第一天就深度理解你的项目且越用越好。其核心功能包括冷启动装架、渐进式信息披露、多模块编排和自我进化，全部由项目真实代码驱动，不依赖任何大模型供应商，也不占用运行时 token。适合于希望提升开发效率、减少重复错误并实现持续改进的软件开发团队使用。",2,"2026-06-11 02:47:07","CREATED_QUERY"]