diff --git a/README.md b/README.md index e02f410..9d82904 100644 --- a/README.md +++ b/README.md @@ -532,6 +532,7 @@ * [**工程实践**](docs/references/quality-gates-and-pitfalls.md): 项目架构、代码组织、开发经验、AI 编程质量门禁与常见坑的统一入口。 * [**技术栈**](docs/references/technology-stack.md#reference-technology-stack-十四如何选择技术栈): 常见软件系统技术栈、选型维度、组合案例与初学者学习路径。 * [**研究域治理契约**](docs/research/research-domain-contract.md): 研究域的结构、raw 原始事实层、成熟度、证据、沉淀和归档规则。 +* [**研究迁移综合**](docs/research/research-transfer-synthesis.md): 用对标拆解、改良迭代和杂交创新把研究转成可执行路线。 * [**Harness 工程解析**](docs/research/harness/harness-engineering.md): Harness Engineering 的工程控制、评估器与反馈闭环解析。 * [**OpenAI Codex 研究域**](docs/research/openai-codex/README.md): 官方 coding agent 工具源码研究对象。 * [**Claude Code Best Practice 研究域**](docs/research/shanraisshan-claude-code-best-practice/README.md): Agentic Engineering 方法论对标研究对象。 diff --git a/assets/ai-citation/llms-full.txt b/assets/ai-citation/llms-full.txt index f9e905b..f460a95 100644 --- a/assets/ai-citation/llms-full.txt +++ b/assets/ai-citation/llms-full.txt @@ -79,6 +79,7 @@ GEOFlow 的关键启发是：GEO 不是关键词堆砌，而是内容工程链 - docs/research/README.md：新技术、技术栈、优秀 repo、工程范式和工具趋势研究入口。 - docs/research/research-domain-contract.md：研究域的结构、raw 原始事实层、成熟度、证据、沉淀和归档规则。 - docs/research/research-value-application-map.md：研究体系给用户带来的价值、核心启示、应用位置和下沉路线。 +- docs/research/research-transfer-synthesis.md：将对标拆解、改良迭代和杂交创新转成可执行研究路线。 - docs/research/harness/harness-engineering.md：Harness Engineering 的工程控制、评估器与反馈闭环解析。 - docs/research/aider-ai-aider/README.md：终端 AI 结对编程工具研究对象。 - docs/research/aider-ai-aider/analysis.md：Aider-AI/aider 的结构化研究结论、可借鉴点、风险和下一轮任务。 diff --git a/docs/README.md b/docs/README.md index 979ecf5..03c4489 100644 --- a/docs/README.md +++ b/docs/README.md @@ -17,7 +17,7 @@ | [concepts](./concepts/) | 核心概念、问题求解、关键词系统与工程思想 | [问题求解](./concepts/problem-solving.md) / [拼好码](./concepts/glue-coding.md) / [关键词系统](./concepts/keyword-system.md) | | [philosophy](./philosophy/) | 哲学方法论、思维模型与底层认知模型 | [思维模型](./philosophy/thinking-models.md) / [方法论工具箱](./philosophy/methodology-toolbox.md) | | [references](./references/) | 工程实践、技术栈、模板和检查清单 | [项目架构模板](./references/project-architecture-template.md) / [质量门禁](./references/quality-gates-and-pitfalls.md) | -| [research](./research/) | 新技术、优秀 repo 与工程范式研究 | [研究域治理契约](./research/research-domain-contract.md) / [Harness 研究对象](./research/harness/) | +| [research](./research/) | 新技术、优秀 repo 与工程范式研究 | [研究域治理契约](./research/research-domain-contract.md) / [研究迁移综合](./research/research-transfer-synthesis.md) | | [workflow](./workflow/) | 开发流程、质量门禁和交付闭环 | [开发流程](./workflow/development-process.md) |
@@ -78,6 +78,7 @@ - [README](./research/README.md) - 研究笔记索引。 - [研究域治理契约](./research/research-domain-contract.md) - 研究域的结构、raw 原始事实层、成熟度、证据、沉淀和归档规则。 - [研究价值与应用地图](./research/research-value-application-map.md) - 研究体系给用户带来的价值、核心启示、应用位置和下沉路线。 +- [研究迁移综合](./research/research-transfer-synthesis.md) - 将对标拆解、改良迭代和杂交创新转成可执行研究路线。 - [Harness 研究对象](./research/harness/README.md) - Harness Engineering 的工程控制、评估器与反馈闭环研究对象。 - [Harness 工程解析](./research/harness/harness-engineering.md) - Harness Engineering 的工程控制、评估器与反馈闭环解析。 - [tmux 蜂群协作](./research/tmux-ai-swarm.md) - 用 tmux 让多个 AI 终端可感知、可调度、可救援的实验性协作范式。 diff --git a/docs/research/AGENTS.md b/docs/research/AGENTS.md index 6af211b..ee3bd47 100644 --- a/docs/research/AGENTS.md +++ b/docs/research/AGENTS.md @@ -19,6 +19,7 @@ research/ ├── README.md # 索引入口：研究对象与研究笔记导航 ├── research-domain-contract.md # 研究域治理契约：结构、分层、成熟度、证据和归档规则 ├── research-value-application-map.md # 研究价值与应用地图：用户价值、核心启示和下沉路线 +├── research-transfer-synthesis.md # 研究迁移综合：对标拆解、改良迭代、杂交创新和验证动作 ├── harness/ │ ├── README.md │ ├── harness-engineering.md @@ -108,6 +109,7 @@ research/ - 外部仓库研究对象采用“一仓库一研究域”，目录名使用 `-` 的小写短横线形式。 - `raw/` 是原始事实层，只保存拉取到本地的一手材料；分析判断写入上一级 `README.md`、`analysis.md` 或 `decisions.md`。 - `research-value-application-map.md` 是研究体系的转化入口，用于说明研究给用户带来的价值、启示、应用位置和下沉路线。 +- `research-transfer-synthesis.md` 是横向迁移入口，用于把 P1/P2 研究对象拆成机制、迁移边界、改良动作和验证指标。 - GitHub 仓库 raw 层通过 `python3 scripts/fetch-research-raw.py` 刷新；不要手工改写 `*.raw.*` 文件。 - 单次短篇观察可以先写成独立 `.md` 文档；如果对象会持续演化，应迁入对象目录。 - 新增研究对象目录或研究 `.md` 文件时，必须同步更新 `README.md`、`metadata/taxonomy.yml` 和必要的 `redirects.yml`。 @@ -118,6 +120,7 @@ research/ ## 质量要求 - 不写新闻转述，要给出判断、边界、采用建议和后续观察点。 +- L2 研究不能只写“可借鉴点”，必须写清对标拆解、可迁移做法、不可迁移条件、下一步试用动作和验证指标。 - 对不确定信息标注“待验证”或 TODO。 - 引入外部事实时优先引用官方文档、原始仓库、论文或可信一手来源。 - 修改后必须运行 `make sync-doc-toc` 和 `make test`。 diff --git a/docs/research/README.md b/docs/research/README.md index 2c83e95..0f3f1ca 100644 --- a/docs/research/README.md +++ b/docs/research/README.md @@ -14,6 +14,7 @@ |:---|:---| | [研究域治理契约](research-domain-contract.md) | 研究域的结构、raw 原始事实层、成熟度、证据、沉淀和归档规则。 | | [研究价值与应用地图](research-value-application-map.md) | 研究体系给用户带来的价值、核心启示、应用位置和下沉路线。 | +| [研究迁移综合](research-transfer-synthesis.md) | 将对标拆解、改良迭代和杂交创新转成可执行研究路线。 | | [Harness 研究对象](harness/) | 工程控制、评估器、反馈闭环与 AI 生成系统可靠性。 | | [tmux 蜂群协作](tmux-ai-swarm.md) | 用 tmux 让多个 AI 终端可感知、可调度、可救援的实验性协作范式。 | | [Aider-AI/aider 研究域](aider-ai-aider/) | 终端 AI 结对编程工具。 | @@ -41,6 +42,7 @@ - [研究域治理契约](research-domain-contract.md) - 研究域的结构、raw 原始事实层、成熟度、证据、沉淀和归档规则。 - [研究价值与应用地图](research-value-application-map.md) - 研究体系给用户带来的价值、核心启示、应用位置和下沉路线。 +- [研究迁移综合](research-transfer-synthesis.md) - 将对标拆解、改良迭代和杂交创新转成可执行研究路线。 - [Harness 研究对象](harness/README.md) - 工程控制、评估器、反馈闭环与 AI 生成系统可靠性。 - [Harness 工程解析](harness/harness-engineering.md) - Harness Engineering 的工程控制、评估器与反馈闭环解析。 - [tmux 蜂群协作](tmux-ai-swarm.md) - 用 tmux 让多个 AI 终端可感知、可调度、可救援的实验性协作范式。 diff --git a/docs/research/ai-for-developers-awesome-vibe-coding/analysis.md b/docs/research/ai-for-developers-awesome-vibe-coding/analysis.md index 9685200..9c87818 100644 --- a/docs/research/ai-for-developers-awesome-vibe-coding/analysis.md +++ b/docs/research/ai-for-developers-awesome-vibe-coding/analysis.md @@ -2,43 +2,63 @@ ## 本轮结论 -- 这是轻量级 awesome list，价值在于补充 Vibe Coding 工具和资料的横向发现，不适合作为方法论主线。 -- 仓库本体几乎只有 `readme.md`，说明它的核心资产是人工维护的分类索引，而不是可运行系统。 -- 更适合作为外部资源发现源和分类词表来源，后续应把稳定条目沉淀到 `assets/external-resources/`，而不是直接复制列表。 +`ai-for-developers/awesome-vibe-coding` 的核心价值不是深度判断，而是轻量资源雷达。它用一个 +README 把 Web builder、IDE、移动工具、插件、本地应用和 CLI 工具粗分出来，适合帮助本仓发现 +候选资源和补分类词表。 + +本仓不能直接复制它的条目，因为它缺少结构化字段、状态、许可证、最后检查时间和采用风险。正确用法是： +把它作为 `assets/external-resources/` 的候选输入源，经过二次筛选后再进入本地资源注册表。 ## 本地证据 - 研究对象：`ai-for-developers/awesome-vibe-coding` - 当前研究角色：精选 Vibe Coding 资料清单 -- 本轮成熟度：L1 初步理解 - 原始仓库：`raw/repository/` - 原始来源清单：`raw/sources.yml` - 事实摘要：`domain.yml` -## 结构观察 +## 对标拆解 -- 根目录只有 `readme.md`，没有脚本、测试、数据源或生成管线。 -- README 以 Web-Based Builders、Editors and IDEs、Mobile Tools、Extensions & Plugins、Desktop & Local Apps、CLI Tools 等类别组织。 -- 结构更偏资源目录，不承担工程实现、课程或 Agent 工作流定义。 +| 项 | 内容 | +|:---|:---| +| 参考对象 | `ai-for-developers/awesome-vibe-coding` | +| 它解决的核心问题 | 快速发现 Vibe Coding 工具生态中的候选对象 | +| 核心机制 | 单 README 分类索引，按工具形态组织入口 | +| 真正带来结果的动作 | 用低成本分类让读者知道生态里有哪些工具族 | +| 可迁移做法 | 补充本仓资源分类、发现候选工具、观察工具族变化 | +| 不可迁移条件 | 不直接复制条目，不把 awesome list 当推荐结论 | +| 下一步试用动作 | 抽取分类词，与 `assets/external-resources/categories.yml` 做对照 | -## 可借鉴点 +## 改良迭代 -- 可借鉴它对 Vibe Coding 工具生态的分类标签，用于补充本仓外部资源注册表的 category 体系。 -- 适合作为低频巡检对象：只提取新增高质量工具，不跟随每个条目做深度研究。 -- 可用它校验本仓是否遗漏 Web builder、IDE、CLI、local app、plugin 等工具族。 +| 改良目标 | 原模式 | 本仓版本 | 验证指标 | +|:---|:---|:---|:---| +| 资源发现 | README 手工分类 | 候选资源进入本地注册表前先二次筛选 | 新资源有 category、source、status、last_checked | +| 分类补齐 | Web / IDE / CLI 等工具族 | 本仓资源 category 增加缺失工具族 | 分类能覆盖 Web builder、IDE agent、CLI、plugin、local app | +| 候选升级 | 条目停留在列表 | 高价值条目升级为独立研究域 | 进入 P1/P2 候选必须有采用理由和风险 | -## 风险和边界 +## 可迁移清单 -- 没有机器可读数据源，质量依赖维护者手工更新。 -- 缺少采用判断和风险说明，不能直接作为推荐清单。 -- 条目多但深度浅，进入本仓前必须二次筛选。 +- 使用它补全 Vibe Coding 工具族分类。 +- 将条目作为资源候选，不作为最终推荐。 +- 对重复出现的工具族提取关键词，反馈到关键词系统。 +- 对高频出现的 coding agent、IDE agent、CLI 工具建立 P1/P2 研究候选。 -## 下一轮研究任务 +## 不可迁移清单 -- 抽取其分类体系，与 `assets/external-resources/categories.yml` 做对照。 -- 只选择与 coding agent、CLI、IDE agent 强相关的条目进入深度研究候选。 +- 不复制整张 awesome list。 +- 不把没有许可证、维护状态和风险说明的条目放进推荐区。 +- 不把它当作学习路径或工程规范。 + +## 验证动作 + +| 动作 | 成功信号 | 失败信号 | +|:---|:---|:---| +| 抽取分类词并对照本仓资源分类 | 发现缺失分类并能补齐 | 分类无变化，只多一批链接 | +| 抽样 20 条资源做二次筛选 | 每条有采用/不采用理由 | 仍然只是链接搬运 | +| 挑出 3 个高价值工具进入候选研究 | 能说明为什么值得深挖 | 候选没有优先级和风险 | ## 沉淀判断 -- 本轮只完成 L1 理解，不直接迁入 concepts、references、workflow 或 skills。 -- 只有经过 L2 源码阅读、实验验证或交叉对照后的结论，才进入稳定层。 \ No newline at end of file +- 稳定结果进入 `assets/external-resources/` 和 `metadata/taxonomy.yml`。 +- 本研究域保持 P3 低频雷达，不升级为方法论主线。 diff --git a/docs/research/aider-ai-aider/analysis.md b/docs/research/aider-ai-aider/analysis.md index a077fc5..994dc57 100644 --- a/docs/research/aider-ai-aider/analysis.md +++ b/docs/research/aider-ai-aider/analysis.md @@ -2,43 +2,63 @@ ## 本轮结论 -- Aider 是成熟的终端 AI 结对编程工具，核心价值在 Git 友好、本地仓库理解、多模型适配和测试/提交闭环。 -- 它不是 IDE 产品，而是 terminal-first 的 repo editing loop；这让它特别适合研究“AI 如何安全修改真实仓库”。 -- 本仓应重点吸收它的 Git 工作流、repo map、lint/test 反馈循环和命令行交互边界。 +`Aider-AI/aider` 的核心价值不是终端聊天，而是 Git 驱动的 AI 编辑闭环。它把仓库状态、编辑格式、 +repo map、命令执行、lint/test 和提交协作放进同一条循环，让 AI 修改始终能被 diff、验证、回滚和审查。 + +本仓最应该迁移的是“AI 修改必须进入证据链”：任何文档、研究、脚本或资源变更，都要能说明 diff 范围、 +验证命令、失败修复和提交边界。 ## 本地证据 - 研究对象：`Aider-AI/aider` - 当前研究角色：终端 AI 结对编程工具 -- 本轮成熟度：L1 初步理解 - 原始仓库：`raw/repository/` - 原始来源清单：`raw/sources.yml` - 事实摘要：`domain.yml` +- 深度证据：`deep-dive.md` -## 结构观察 +## 对标拆解 -- 根目录包含 `aider/`、`benchmark/`、`tests/`、`scripts/`、`requirements/` 和 `pyproject.toml`。 -- `aider/` 是主实现目录，`tests/` 和 `benchmark/` 说明它不仅是演示工具，而是有持续验证和性能/能力评估意识。 -- README 强调 cloud/local LLM、codebase map、Git integration、linting/testing、copy/paste to web chat 等能力。 +| 项 | 内容 | +|:---|:---| +| 参考对象 | `Aider-AI/aider` | +| 它解决的核心问题 | 让 AI 对真实仓库的修改可 diff、可测试、可提交、可回滚 | +| 核心机制 | `repo.py` 管 Git 状态，`repomap.py` 压缩上下文，`coders/` 定义编辑协议，`linter.py` 接入反馈 | +| 真正带来结果的动作 | 把 AI 输出变成 Git 工作流里的可审查补丁，而不是孤立文本 | +| 可迁移做法 | dirty state 检查、diff 审查、门禁命令、验证证据和提交叙事 | +| 不可迁移条件 | 不复制完整终端产品、多模型配置和 Python 编辑器实现 | +| 下一步试用动作 | 在 `docs/workflow/` 沉淀“AI 修改 -> diff 审查 -> make test -> commit”闭环 | -## 可借鉴点 +## 改良迭代 -- 把 Git 状态作为 AI 修改的核心护栏：每轮修改都能被 diff、commit、回滚和审查。 -- 把测试和 lint 作为对话内反馈，而不是任务结束后的附属动作。 -- 终端工具可以避免复杂 UI，但必须把 repo context、命令回显和失败恢复做扎实。 +| 改良目标 | 原模式 | 本仓版本 | 验证指标 | +|:---|:---|:---|:---| +| Git 状态护栏 | Aider 围绕 Git dirty state 和 commit 工作 | 每次任务先看 `git status`，不覆盖用户改动 | 变更说明能区分用户改动和本轮改动 | +| 文档上下文压缩 | Aider 用 repo map 选择上下文 | 本仓建立 research/docs 入口地图和索引校验 | 新文档不会漏进 README、metadata、llms | +| 反馈循环 | Aider 把 lint/test 反馈接进对话 | 本仓统一用 `make test` 做文档门禁 | 修改后失败项能回到具体文件修复 | -## 风险和边界 +## 可迁移清单 -- 终端优先意味着非程序员上手门槛高于 IDE 插件。 -- 多模型和多语言支持会带来配置面复杂度。 -- 其很多文档在官网侧，研究时要同步看本地源码和外部文档。 +- 把“修改前检查工作区状态”写成所有 AI 工程任务默认动作。 +- 把 `make test`、`git diff --check` 和关键脚本输出纳入交付说明。 +- 为研究域建立文档地图或索引生成机制，减少长文档漂移。 +- 对大文件修改优先使用局部 patch，避免全文件重写带来无关 diff。 -## 下一轮研究任务 +## 不可迁移清单 -- 重点阅读 `aider/` 的 repo map、Git 操作和 test/lint 调用路径。 -- 把 Aider 的 terminal loop 抽象为本仓 `workflow/` 可复用闭环。 +- 不把本仓变成 Aider 竞品。 +- 不复制其多模型兼容层、coder 实现和交互式命令系统。 +- 不把 repo map 当成万能方案；本仓优先解决 Markdown 索引漂移和研究域路由。 + +## 验证动作 + +| 动作 | 成功信号 | 失败信号 | +|:---|:---|:---| +| 为一次文档任务记录状态、diff、门禁和提交说明 | 后续审查能复现变更链路 | 只能从对话里猜为什么这么改 | +| 抽样新增文档后跑索引检查 | README、metadata、llms 同步 | 新文档存在但入口缺失 | +| 对同一类研究文档使用固定分析骨架 | 读者能横向比较对象 | 每篇分析结构不同、不可比较 | ## 沉淀判断 -- 本轮只完成 L1 理解，不直接迁入 concepts、references、workflow 或 skills。 -- 只有经过 L2 源码阅读、实验验证或交叉对照后的结论，才进入稳定层。 \ No newline at end of file +- 稳定结论应下沉到 `docs/workflow/` 的 AI 修改闭环。 +- `deep-dive.md` 保留源码证据；本文件负责把证据转成迁移动作。 diff --git a/docs/research/cline-cline/analysis.md b/docs/research/cline-cline/analysis.md index ed01109..01ce7dd 100644 --- a/docs/research/cline-cline/analysis.md +++ b/docs/research/cline-cline/analysis.md @@ -2,43 +2,63 @@ ## 本轮结论 -- Cline 是多表面 coding agent 产品，覆盖 VS Code Extension、CLI、Kanban、SDK 和 JetBrains Plugin。 -- 它的研究重点不是单一模型调用，而是 agent 工具面、编辑器集成、规则/技能、评估和产品化分层。 -- 本仓应重点吸收它的多入口架构、规则文件约定、evals 目录和 extension/webview 分离。 +`cline/cline` 的核心价值不是“VS Code 插件怎么做”，而是展示了成熟 agent 产品会从单入口扩展成 +IDE、CLI、SDK、rules、skills、examples、evals 和发布脚本共同组成的平台。 + +本仓最应该迁移的是入口契约：人类阅读入口、AI 上下文入口、脚本入口、skill 入口、资源入口和 +metadata 入口不能各自为政，必须写清输入、输出、owner、验证命令和更新策略。 ## 本地证据 - 研究对象：`cline/cline` - 当前研究角色：IDE/SDK/CLI 自主编码 Agent -- 本轮成熟度：L1 初步理解 - 原始仓库：`raw/repository/` - 原始来源清单：`raw/sources.yml` - 事实摘要：`domain.yml` +- 深度证据：`deep-dive.md` -## 结构观察 +## 对标拆解 -- 根目录包含 `.agents/`、`.claude/`、`.cline/`、`.clinerules/`、`apps/`、`sdk/`、`evals/` 和 `package.json`。 -- `apps/` 和 `sdk/` 表明它已经从单一 VS Code 插件演化成多产品面。 -- README 明确列出 CLI、Kanban、VS Code Extension、JetBrains Plugin、SDK、Plan and Act、Rules and Skills。 +| 项 | 内容 | +|:---|:---| +| 参考对象 | `cline/cline` | +| 它解决的核心问题 | 让 agent 能力跨 IDE、CLI、SDK、规则、技能、示例和评估保持一致 | +| 核心机制 | `apps/` 多入口，`sdk/` 可复用能力，`.clinerules/` 规则，`.agents/skills` 技能，`evals/` 评估 | +| 真正带来结果的动作 | 把入口和规则文件化，让不同使用表面共享同一套行为边界 | +| 可迁移做法 | 为本仓所有入口建立入口矩阵和更新契约 | +| 不可迁移条件 | 不复制 VS Code 插件、SDK、hub 服务或复杂前端 UI | +| 下一步试用动作 | 梳理人类入口、AI 入口、脚本入口、skill 入口、资源入口和 metadata 入口 | -## 可借鉴点 +## 改良迭代 -- 把 Agent 能力拆成产品表面、SDK、规则、技能和评估，而不是把所有逻辑塞进一个入口。 -- 规则文件和技能目录是让用户控制 agent 行为的关键资产。 -- IDE agent 需要 plan/act 分离，降低自动执行的不可控风险。 +| 改良目标 | 原模式 | 本仓版本 | 验证指标 | +|:---|:---|:---|:---| +| 多入口一致性 | Cline 用 apps/sdk/rules/examples 承载不同入口 | 本仓用 README、AGENTS、llms、metadata、scripts、skills 协同 | 新入口新增时能找到 owner 和验证命令 | +| 规则文件化 | Cline 用 `.clinerules/` 固化 agent 行为 | 本仓用根和目录级 `AGENTS.md` 固化规则 | 架构变更后规则同步 | +| 示例驱动 | Cline 用 examples 展示 SDK/agent 用法 | 本仓为关键 workflow 和 skills 增加最小示例 | 用户能按示例复现流程 | -## 风险和边界 +## 可迁移清单 -- 产品面很多，架构复杂度高，直接模仿会带来过高维护成本。 -- 前端、扩展宿主、模型工具调用和评估同时演进，研究需要分层拆解。 -- 作为快速迭代项目，某些目录和命令可能频繁变化。 +- 写一张入口矩阵：入口、目标读者、输入、输出、owner、验证命令、更新触发。 +- 把 `llms.txt`、`llms-full.txt`、`metadata/taxonomy.yml` 作为 AI 入口，而不是附属文件。 +- 把 `scripts/` 和 `skills/` 作为执行入口，明确自动执行边界。 +- 为关键 workflow 增加最小示例，避免只写原则。 -## 下一轮研究任务 +## 不可迁移清单 -- 拆读 `apps/`、`sdk/`、`evals/` 的边界，形成 IDE agent 架构图。 -- 提炼 Cline 的 rules/skills 模式，和本仓 `skills/` 体系对照。 +- 不提前建设 SDK 或 hub 服务。 +- 不为“平台感”增加不必要目录和运行时。 +- 不把多入口扩张理解成所有能力都要产品化；本仓优先做文档和 Agent 可读入口一致性。 + +## 验证动作 + +| 动作 | 成功信号 | 失败信号 | +|:---|:---|:---| +| 建立入口矩阵 | 任意入口变更能找到同步位置 | 新增入口后 README、metadata、llms 漂移 | +| 抽样一个 skill 写清输入输出和验证 | Agent 能按规则触发和验证 | skill 只是 prompt 文本 | +| 抽样一个 workflow 增加最小示例 | 用户能复现流程 | 只能理解原则，不能操作 | ## 沉淀判断 -- 本轮只完成 L1 理解，不直接迁入 concepts、references、workflow 或 skills。 -- 只有经过 L2 源码阅读、实验验证或交叉对照后的结论，才进入稳定层。 \ No newline at end of file +- 稳定结论应下沉到 `docs/references/` 的多入口仓库结构模板或 `docs/workflow/` 的入口维护规则。 +- `deep-dive.md` 保留源码证据；本文件负责把证据转成迁移动作。 diff --git a/docs/research/daotin-ai-coding/analysis.md b/docs/research/daotin-ai-coding/analysis.md index 53ef399..c52fc86 100644 --- a/docs/research/daotin-ai-coding/analysis.md +++ b/docs/research/daotin-ai-coding/analysis.md @@ -2,43 +2,62 @@ ## 本轮结论 -- 这是中文 AI Coding 资料与经验汇总，价值在主题覆盖，不在工程实现。 -- README 将内容分成 AI 方法论、AI 工具、AI 经验、AI 科普、AI 实战、AI 思考、AI 提示词、MCP 等块。 -- 适合作为本仓中文语境资源补充和关键词候选来源。 +`Daotin/ai-coding` 的核心价值是中文 AI Coding 主题雷达。它覆盖 Cursor、Claude Code、Codex、MCP、 +AGENTS.md、提示词、经验和实战，适合帮助本仓观察中文社区正在关心什么。 + +本仓不能把它当作工程标准来源。正确用法是：抽取高频主题、关键词和候选资源，再用本仓的 raw、 +analysis、deep-dive 和门禁流程二次验证。 ## 本地证据 - 研究对象：`Daotin/ai-coding` - 当前研究角色：AI Coding 经验汇总 -- 本轮成熟度：L1 初步理解 - 原始仓库：`raw/repository/` - 原始来源清单：`raw/sources.yml` - 事实摘要：`domain.yml` -## 结构观察 +## 对标拆解 -- 根目录包含 `README.md`、`package.json`、`BACKUP/` 和 GitHub 配置。 -- 没有明显的核心应用源码，主体是文档索引和资料组织。 -- 分类覆盖 Cursor、Claude Code、Codex、MCP、AGENTS.md 等 AI Coding 主题。 +| 项 | 内容 | +|:---|:---| +| 参考对象 | `Daotin/ai-coding` | +| 它解决的核心问题 | 汇总中文 AI Coding 主题、工具和经验入口 | +| 核心机制 | README 多主题索引，覆盖方法论、工具、经验、实战、提示词和 MCP | +| 真正带来结果的动作 | 快速暴露中文社区高频关注点 | +| 可迁移做法 | 关键词候选、资源候选、MCP/AGENTS/Codex/Claude Code 主题雷达 | +| 不可迁移条件 | 不把资料聚合当作验证结论，不复制为本仓标准 | +| 下一步试用动作 | 抽取高频主题并映射到 `docs/concepts/keyword-system.md` | -## 可借鉴点 +## 改良迭代 -- 可借鉴它的中文主题颗粒度，用于补本仓关键词系统和资源分类。 -- 适合作为“中文社区正在关心什么”的观察点。 -- 可把其中高价值链接转入 `assets/external-resources/` 做结构化管理。 +| 改良目标 | 原模式 | 本仓版本 | 验证指标 | +|:---|:---|:---|:---| +| 主题发现 | 多主题资料汇总 | 关键词系统候选和资源注册表候选 | 候选有来源和采用理由 | +| 经验筛选 | 经验链接聚合 | 经验必须转成短句、流程或检查项 | 经验不再只是外链 | +| 工具观察 | 工具清单 | 高价值工具升级为独立研究域 | 升级有优先级和边界 | -## 风险和边界 +## 可迁移清单 -- 资料聚合多于一手验证，不适合作为工程标准来源。 -- 内容质量可能不均，需要二次核验。 -- 如果直接复制，会让本仓变成资源堆。 +- 抽取中文 AI Coding 高频词。 +- 观察 MCP、AGENTS.md、Codex、Claude Code 相关资源热度。 +- 将高价值资源进入 `assets/external-resources/`。 +- 将稳定经验候选进入 `docs/getting-started/` 或 `docs/workflow/`。 -## 下一轮研究任务 +## 不可迁移清单 -- 抽取与 MCP、AGENTS.md、Claude Code、Codex 相关的高频词。 -- 筛选能进入本仓 references 或 concepts 的稳定经验。 +- 不把聚合链接当作采用建议。 +- 不让本仓变成资料堆。 +- 不把未经验证的经验写入工程规范。 + +## 验证动作 + +| 动作 | 成功信号 | 失败信号 | +|:---|:---|:---| +| 抽取 20 个高频关键词 | 关键词能进入概念系统候选 | 关键词无定义和用途 | +| 筛选 10 条资源 | 资源进入本地注册表并有状态 | 只复制链接 | +| 抽取 5 条经验 | 每条转成动作或检查项 | 经验仍是口号 | ## 沉淀判断 -- 本轮只完成 L1 理解，不直接迁入 concepts、references、workflow 或 skills。 -- 只有经过 L2 源码阅读、实验验证或交叉对照后的结论，才进入稳定层。 \ No newline at end of file +- 稳定结果进入关键词系统、外部资源注册表和 workflow。 +- 本研究域保持 P3 中文主题雷达。 diff --git a/docs/research/datawhalechina-easy-vibe/analysis.md b/docs/research/datawhalechina-easy-vibe/analysis.md index a365d40..75b8b90 100644 --- a/docs/research/datawhalechina-easy-vibe/analysis.md +++ b/docs/research/datawhalechina-easy-vibe/analysis.md @@ -2,43 +2,63 @@ ## 本轮结论 -- Easy Vibe 是中文 Vibe Coding 课程型站点，重点在学习路径、课程包装和面向不同目标的路线分流。 -- 它比单纯 awesome list 更接近产品化教程，有 `docs/`、`config/`、`scripts/`、`llms.txt`、`AGENTS.md`、`CLAUDE.md` 等 AI/文档工程资产。 -- 本仓应重点吸收它的学习路径分层、课程入口设计、Agent 文档入口和多语言/站点化组织方式。 +`datawhalechina/easy-vibe` 的核心价值是课程产品化：它不是单篇教程，而是把 Vibe Coding 按用户目标、 +学习阶段、站点化文档、AI 可读入口和课程资源组织成可持续学习系统。 + +本仓最应该迁移的是学习路径分流：新手、原型构建者、全栈产品用户、AI-Native 进阶用户不应该读同一条路径。 +但本仓不能直接复制站点结构，应该把它改良成 `getting-started` 的用户身份和产出导向路线。 ## 本地证据 - 研究对象：`datawhalechina/easy-vibe` - 当前研究角色：中文分阶段交互式课程 -- 本轮成熟度：L1 初步理解 - 原始仓库：`raw/repository/` - 原始来源清单：`raw/sources.yml` - 事实摘要：`domain.yml` +- 深度证据：`deep-dive.md` -## 结构观察 +## 对标拆解 -- 根目录包含 `docs/`、`docs-readme/`、`config/`、`scripts/`、`assets/`、`Dockerfile`、`package.json`。 -- README 将用户分成 fast first win、idea to prototype、full-stack products、AI-Native advanced workflow、reference material 等学习路径。 -- 存在 `AGENTS.md`、`CLAUDE.md` 和 `llms.txt`，说明它已经考虑 AI Agent 可读入口。 +| 项 | 内容 | +|:---|:---| +| 参考对象 | `datawhalechina/easy-vibe` | +| 它解决的核心问题 | 让不同目标的中文用户知道从哪条路线开始学习 Vibe Coding | +| 核心机制 | `docs/` 课程内容、站点配置、脚本、`AGENTS.md`、`CLAUDE.md`、`llms.txt` | +| 真正带来结果的动作 | 用用户目标分流学习路径，而不是只按技术栈罗列知识 | +| 可迁移做法 | 新手 first win、idea to prototype、full-stack、AI-Native 进阶路径 | +| 不可迁移条件 | 不复制站点工程和大体量课程目录，本仓保持轻量文档知识库 | +| 下一步试用动作 | 重构 `docs/getting-started/learning-map.md` 的用户身份和阶段分流 | -## 可借鉴点 +## 改良迭代 -- 学习路线不应只按技术栈组织，也应按用户目标和阶段组织。 -- 课程站点可以同时服务人类读者和 AI 助手，关键是保留 `llms.txt` 与目录规则。 -- 适合对照本仓 getting-started 和 docs/README 的新手路径设计。 +| 改良目标 | 原模式 | 本仓版本 | 验证指标 | +|:---|:---|:---|:---| +| 用户分流 | 按学习目标给路线 | 零基础、开发者、创业者、维护者、高阶 Agent 用户 | 用户能在 30 秒内找到路线 | +| 产出导向 | 先给 first win | 每个阶段写清能做出什么 | 路线不再只列文档链接 | +| AI 可读入口 | `AGENTS.md`、`CLAUDE.md`、`llms.txt` | 本仓 `AGENTS.md`、`llms.txt`、`llms-full.txt` 协同 | AI 能按入口读取上下文 | -## 风险和边界 +## 可迁移清单 -- 课程内容规模大且多语言/多目录，直接迁移会增加维护成本。 -- 它偏学习体验，不等同于企业级工程治理模板。 -- 站点生成和课程结构需要拆开研究，不能混成一个结论。 +- 让入门路径先回答“你会做出什么”，再讲概念。 +- 按用户身份和目标组织学习地图。 +- 在每个阶段写清前置条件、产出、验证方式和下一步。 +- 保持 AI 可读入口和人类入口同步。 -## 下一轮研究任务 +## 不可迁移清单 -- 读取 `docs/` 的学习路径结构，抽象为本仓学习地图改进建议。 -- 研究 `AGENTS.md`、`CLAUDE.md`、`llms.txt` 如何服务 AI 读取。 +- 不把本仓变成大型课程站点。 +- 不直接迁移其目录和站点构建方式。 +- 不把课程包装等同于工程治理。 + +## 验证动作 + +| 动作 | 成功信号 | 失败信号 | +|:---|:---|:---| +| 抽样重写一个 getting-started 路线 | 用户能按身份选择路径 | 所有人仍读同一条线 | +| 给每阶段补产出和验证 | 每阶段有可见成果 | 仍只是资料链接 | +| 检查 AI 入口同步 | llms 和 README 指向一致 | AI 入口缺最新路径 | ## 沉淀判断 -- 本轮只完成 L1 理解，不直接迁入 concepts、references、workflow 或 skills。 -- 只有经过 L2 源码阅读、实验验证或交叉对照后的结论，才进入稳定层。 \ No newline at end of file +- 稳定结论进入 `docs/getting-started/` 和 `docs/README.md`。 +- 本研究域保持 P2 教程产品化对标对象。 diff --git a/docs/research/datawhalechina-vibe-vibe/analysis.md b/docs/research/datawhalechina-vibe-vibe/analysis.md index d742637..6424236 100644 --- a/docs/research/datawhalechina-vibe-vibe/analysis.md +++ b/docs/research/datawhalechina-vibe-vibe/analysis.md @@ -2,43 +2,62 @@ ## 本轮结论 -- Vibe Vibe 是面向零基础用户的中文 AI 编程指南，核心价值是把 Vibe Coding 讲成可学习、可部署、可演示的课程。 -- 仓库包含 `docs/`、`demos/`、`Dockerfile`、`docker-compose.yml`，说明它强调教程、示例和私有化部署。 -- 本仓应吸收它对零基础用户的解释方式和 demo 驱动学习路径，但工程治理层仍需本仓自己定义。 +`datawhalechina/vibe-vibe` 的核心价值是把零基础 Vibe Coding 讲成“能学、能看、能部署、能演示”的课程。 +它用 `docs/`、`demos/`、Docker 和部署说明降低学习门槛，强调从概念走向可见产物。 + +本仓最应该迁移的是 demo 驱动学习：概念文档必须有验证层，否则用户读完只有认知，没有交付感。 ## 本地证据 - 研究对象：`datawhalechina/vibe-vibe` - 当前研究角色：中文零基础系统教程 -- 本轮成熟度：L1 初步理解 - 原始仓库：`raw/repository/` - 原始来源清单：`raw/sources.yml` - 事实摘要：`domain.yml` +- 深度证据：`deep-dive.md` -## 结构观察 +## 对标拆解 -- 根目录包含 `docs/`、`demos/`、`package.json`、`pnpm-lock.yaml`、`Dockerfile`、`docker-compose.yml`。 -- README 的核心理念、快速开始、私有化部署、教程定位、进阶版预告和学习产出结构清晰。 -- 课程形态比工具实现更强，适合作为 onboarding 研究对象。 +| 项 | 内容 | +|:---|:---| +| 参考对象 | `datawhalechina/vibe-vibe` | +| 它解决的核心问题 | 让零基础用户从理解 Vibe Coding 走到运行示例和部署体验 | +| 核心机制 | `docs/` 讲解、`demos/` 示例、Docker 私有化部署、清晰课程定位 | +| 真正带来结果的动作 | 用可运行 demo 把抽象概念落成体验 | +| 可迁移做法 | getting-started 增加最小 demo、部署感和阶段产出 | +| 不可迁移条件 | 不把零基础教程简化为工程标准，不复制课程站点体量 | +| 下一步试用动作 | 为一个核心概念补最小练习或 demo 验证任务 | -## 可借鉴点 +## 改良迭代 -- 零基础内容需要先给学习产出，再给工具和概念。 -- demo 目录能降低抽象教程的理解成本。 -- 私有化部署说明适合补充本仓“教程站点/知识库发布”参考。 +| 改良目标 | 原模式 | 本仓版本 | 验证指标 | +|:---|:---|:---|:---| +| 概念可验证 | demo 目录承接教程 | concepts 后接 practice / workflow 验证 | 读者能运行或检查一个结果 | +| 部署感 | Docker 私有化部署 | 本仓给出知识库/项目交付的最小上线路径 | 用户知道如何从本地到可访问产物 | +| 零基础解释 | 先讲清概念和体验 | getting-started 降低术语密度 | 非程序员能理解第一步 | -## 风险和边界 +## 可迁移清单 -- 面向零基础会简化工程细节，不能直接当作高级工程规范。 -- 大体量课程仓库需要区分原创内容、站点框架和生成资产。 -- 进阶版能力需要继续观察是否真实落地。 +- 每条新手路径至少配一个可验证产物。 +- 把 demo / assignment 作为概念验收层。 +- 在入门文档里强调“交付感”，不要只讲工具安装。 +- 将部署或发布作为早期可选路线。 -## 下一轮研究任务 +## 不可迁移清单 -- 整理它的课程目录和 demo 类型，对照本仓 getting-started。 -- 分析私有化部署部分是否能沉淀到 references。 +- 不把零基础简化表达当作高级工程规范。 +- 不复制 Docker/站点结构作为本仓必需能力。 +- 不把 demo 数量当作质量。 + +## 验证动作 + +| 动作 | 成功信号 | 失败信号 | +|:---|:---|:---| +| 为一个概念补最小练习 | 用户能完成并验证结果 | 练习只是阅读题 | +| 给新手路径补第一个可见产物 | 新手知道第一天做出什么 | 路线仍停在安装工具 | +| 抽样检查 demo 与文档一致 | demo 能解释对应概念 | demo 与正文脱节 | ## 沉淀判断 -- 本轮只完成 L1 理解，不直接迁入 concepts、references、workflow 或 skills。 -- 只有经过 L2 源码阅读、实验验证或交叉对照后的结论，才进入稳定层。 \ No newline at end of file +- 稳定结论进入 `docs/getting-started/`，后续可考虑独立 practice 层。 +- 本研究域保持 P2 零基础课程对标对象。 diff --git a/docs/research/earyantle-vibe-coding-skill/analysis.md b/docs/research/earyantle-vibe-coding-skill/analysis.md index 604222f..03825db 100644 --- a/docs/research/earyantle-vibe-coding-skill/analysis.md +++ b/docs/research/earyantle-vibe-coding-skill/analysis.md @@ -2,43 +2,62 @@ ## 本轮结论 -- 这是把 Vibe Coding 方法沉淀成 Skill 的小型仓库，价值在结构形态而不是代码规模。 -- 根目录有 `SKILL.md`、`references/`、`PUBLISH.md`、`SUBMISSION.md`，说明它关注 skill 打包、发布和提交流程。 -- 本仓应重点对照其 Skill 文档组织方式，反哺 `skills/` 的最小可发布结构。 +`earyantLe/vibe-coding-skill` 的价值在“小型方法论如何封装成 Skill”。它不是大型教程，也不是复杂应用， +但它有 `SKILL.md`、`references/`、发布说明和提交流程，适合研究最小可发布 Skill 的骨架。 + +本仓最应该迁移的是 Skill 产品化边界：一个 Skill 不能只是长提示词，必须有触发条件、输入输出、 +引用资料、约束、验证和发布检查。 ## 本地证据 - 研究对象：`earyantLe/vibe-coding-skill` - 当前研究角色：Vibe Coding Skill / SOP 化 -- 本轮成熟度：L1 初步理解 - 原始仓库：`raw/repository/` - 原始来源清单：`raw/sources.yml` - 事实摘要：`domain.yml` -## 结构观察 +## 对标拆解 -- 根目录包含 `SKILL.md`、`README.md`、`references/`、`PUBLISH.md`、`SUBMISSION.md`、`AGENTS.md`。 -- README 包含文件结构、快速开始、核心内容、方法论、工作流程、约束条件、能力提升。 -- 它不是应用仓库，而是能力封装仓库。 +| 项 | 内容 | +|:---|:---| +| 参考对象 | `earyantLe/vibe-coding-skill` | +| 它解决的核心问题 | 把 Vibe Coding 方法封装成可调用 Skill | +| 核心机制 | `SKILL.md`、`references/`、`PUBLISH.md`、`SUBMISSION.md` | +| 真正带来结果的动作 | 让方法论从文档变成有入口、有资料、有发布流程的能力单元 | +| 可迁移做法 | Skill 最小结构、发布检查、引用资料组织 | +| 不可迁移条件 | 不把小型 Skill 当成完整方法论体系 | +| 下一步试用动作 | 为本仓 skills 建最小发布检查清单 | -## 可借鉴点 +## 改良迭代 -- Skill 应该有清晰入口、引用资料、发布说明和提交说明。 -- 方法论可以通过 `SKILL.md` 固化为可调用能力。 -- 小仓库也能成为研究域，只要对象边界清晰。 +| 改良目标 | 原模式 | 本仓版本 | 验证指标 | +|:---|:---|:---|:---| +| Skill 入口 | 单个 `SKILL.md` | 每个 skill 明确触发、边界、输入输出 | Agent 能判断何时调用 | +| 引用资料 | `references/` 支撑正文 | 引用资料按任务路由读取 | 不一次性加载无关资料 | +| 发布检查 | PUBLISH / SUBMISSION | 本仓 skill 校验和归档规则 | skill 可验证、可维护 | -## 风险和边界 +## 可迁移清单 -- 规模小，缺少复杂场景验证。 -- Skill 的质量要看具体指令密度和可执行性，不应只看目录完整。 -- 不能把它当作完整 Vibe Coding 教程。 +- 为 Skill 补触发条件、输入输出、边界和验证命令。 +- 把长方法论拆成 `SKILL.md` 和 `references/`。 +- 为发布和提交增加检查清单。 +- 将 SOP 化经验转入 skills，而不是留在零散文档。 -## 下一轮研究任务 +## 不可迁移清单 -- 逐段审查 `SKILL.md`，和本仓 `skills/auto-*` 的结构做对照。 -- 提炼可复用的 Skill 发布检查清单。 +- 不把每个经验都做成 Skill。 +- 不用 Skill 包装还没验证的方法。 +- 不因为目录完整就认为能力可用。 + +## 验证动作 + +| 动作 | 成功信号 | 失败信号 | +|:---|:---|:---| +| 抽样一个本仓 skill 做发布检查 | 触发、输入、输出、验证都明确 | 只有提示词正文 | +| 把一条 SOP 转成 skill 候选 | 能说明为什么需要 skill | 文档已经足够却新增复杂度 | +| 校验 references 读取边界 | 只读任务相关资料 | skill 一启动就加载全部资料 | ## 沉淀判断 -- 本轮只完成 L1 理解，不直接迁入 concepts、references、workflow 或 skills。 -- 只有经过 L2 源码阅读、实验验证或交叉对照后的结论，才进入稳定层。 \ No newline at end of file +- 稳定结论进入 `skills/AGENTS.md`、`skills/README.md` 或 skill 创建规范。 +- 本研究域保持 P3 Skill 骨架观察对象。 diff --git a/docs/research/filipecalegario-awesome-vibe-coding/analysis.md b/docs/research/filipecalegario-awesome-vibe-coding/analysis.md index 7dec82d..3113c8b 100644 --- a/docs/research/filipecalegario-awesome-vibe-coding/analysis.md +++ b/docs/research/filipecalegario-awesome-vibe-coding/analysis.md @@ -2,43 +2,63 @@ ## 本轮结论 -- 这是国际语境下较完整的 Vibe Coding awesome list，价值在概念、工具和资料生态的横向扫描。 -- 多语言 README 和分类覆盖 browser tools、IDEs、mobile apps、plugins、local apps、CLI、task management 等。 -- 本仓应把它作为国际资源雷达，而不是直接复制成中文推荐。 +`filipecalegario/awesome-vibe-coding` 的价值在国际语境和多语言 Vibe Coding 雷达。它提供概念定义、 +跨语言表达和工具族分类，适合帮助本仓观察国际生态、术语翻译和资源候选。 + +它不是采用结论。awesome list 的问题是“广而浅”：能告诉你生态里有什么，但不能告诉你哪些真的适合 +中文用户、哪些能进入工程工作流、哪些只是营销壳。 ## 本地证据 - 研究对象：`filipecalegario/awesome-vibe-coding` - 当前研究角色：国际 Vibe Coding 索引 -- 本轮成熟度：L1 初步理解 - 原始仓库：`raw/repository/` - 原始来源清单：`raw/sources.yml` - 事实摘要：`domain.yml` +- 深度证据：`deep-dive.md` -## 结构观察 +## 对标拆解 -- 根目录包含 `README.md`、`README-CN.md`、`README-JP.md`、`README-KR.md`、`README-PT.md`、`contributing.md`、`code-of-conduct.md`。 -- README 先定义 concept，再按工具类型组织。 -- 它有贡献和行为规范，但没有明显自动化数据管线。 +| 项 | 内容 | +|:---|:---| +| 参考对象 | `filipecalegario/awesome-vibe-coding` | +| 它解决的核心问题 | 给国际 Vibe Coding 概念、工具和资料提供横向入口 | +| 核心机制 | 多语言 README、概念定义、工具族分类和贡献说明 | +| 真正带来结果的动作 | 用多语言和多类别降低生态发现成本 | +| 可迁移做法 | 国际术语对照、工具族分类、资源候选池、多语言表达观察 | +| 不可迁移条件 | 不直接采用国际工具推荐，不忽略中文网络、支付和学习环境 | +| 下一步试用动作 | 将工具族分类映射到本仓外部资源 schema 和关键词系统 | -## 可借鉴点 +## 改良迭代 -- 可借鉴国际 Vibe Coding 语境下的工具族分类。 -- 多语言 README 适合观察术语翻译和跨语境表达。 -- 可作为本仓外部资源表的候选来源。 +| 改良目标 | 原模式 | 本仓版本 | 验证指标 | +|:---|:---|:---|:---| +| 国际雷达 | 多语言 awesome list | 本仓资源候选池和关键词候选 | 候选资源进入本地结构化字段 | +| 术语治理 | 多语言 README | 中文术语和英文术语成对记录 | 关键词系统能解释常见英文概念 | +| 工具筛选 | 按工具形态罗列 | 按用户场景、可访问性、维护状态筛选 | 资源推荐不再只看知名度 | -## 风险和边界 +## 可迁移清单 -- awesome list 缺少采用深度和风险评级。 -- 国际语境工具未必适合中文用户网络、支付和学习环境。 -- 条目更新频率和质量需要持续核验。 +- 提取 Vibe Coding 国际语境下的工具族和术语。 +- 将重复出现的工具纳入资源候选，不直接纳入推荐。 +- 观察多语言 README 如何处理术语翻译，反哺本仓关键词系统。 +- 对高价值 CLI、IDE agent、local app 条目建立研究候选。 -## 下一轮研究任务 +## 不可迁移清单 -- 抽取工具分类和术语，更新关键词系统候选。 -- 筛选与 coding agent 强相关的条目进入 P1/P2 研究候选。 +- 不把国际生态列表当作中文用户可用清单。 +- 不把条目数量当作质量。 +- 不把概念定义直接复制到本仓底层概念中。 + +## 验证动作 + +| 动作 | 成功信号 | 失败信号 | +|:---|:---|:---| +| 抽取 30 个条目做本地化筛选 | 能标出可用、待验证、不可用 | 只新增链接，无筛选结论 | +| 抽取术语对照 | 关键词系统新增中英对照候选 | 术语仍散落在资源标题里 | +| 将高频工具族映射到资源 schema | 分类覆盖更完整 | 分类仍无法容纳新工具 | ## 沉淀判断 -- 本轮只完成 L1 理解，不直接迁入 concepts、references、workflow 或 skills。 -- 只有经过 L2 源码阅读、实验验证或交叉对照后的结论，才进入稳定层。 \ No newline at end of file +- 稳定结果进入 `assets/external-resources/`、`docs/concepts/keyword-system.md` 和资源治理文档。 +- 本研究域保持 P2 国际雷达，只有具体工具被验证后才升级为独立研究域。 diff --git a/docs/research/hesreallyhim-awesome-claude-code/analysis.md b/docs/research/hesreallyhim-awesome-claude-code/analysis.md index 24fb978..96d5042 100644 --- a/docs/research/hesreallyhim-awesome-claude-code/analysis.md +++ b/docs/research/hesreallyhim-awesome-claude-code/analysis.md @@ -2,43 +2,63 @@ ## 本轮结论 -- 这是 Claude Code 生态资源索引，但比普通 awesome list 更工程化：有 CSV、data、resources、scripts、tests、templates。 -- 它的研究价值在资源登记、分类、生成/校验管线，而不只是链接数量。 -- 本仓应重点吸收其资源数据化和索引维护方式，用于强化 `assets/external-resources/`。 +`hesreallyhim/awesome-claude-code` 的核心价值不是链接多，而是把 Claude Code 生态资源做成可治理数据资产。 +它有 CSV 主表、动态数据、资源目录、脚本、测试和模板，已经从普通 awesome list 进化成资源登记系统。 + +本仓最应该迁移的是资源治理模型：外部资源必须有主表、字段契约、状态、最后检查时间、许可证、失效标记、 +生成/校验脚本和归档策略。 ## 本地证据 - 研究对象：`hesreallyhim/awesome-claude-code` - 当前研究角色：Claude Code 生态索引 -- 本轮成熟度：L1 初步理解 - 原始仓库：`raw/repository/` - 原始来源清单：`raw/sources.yml` - 事实摘要：`domain.yml` +- 深度证据：`deep-dive.md` -## 结构观察 +## 对标拆解 -- 根目录包含 `THE_RESOURCES_TABLE.csv`、`data/`、`resources/`、`scripts/`、`tests/`、`templates/`、`pyproject.toml`。 -- README 以 Awesome Claude Code 和 Table of Contents 为主入口。 -- 存在 `README_ALTERNATIVES/`，说明它关注不同展示形态。 +| 项 | 内容 | +|:---|:---| +| 参考对象 | `hesreallyhim/awesome-claude-code` | +| 它解决的核心问题 | 让快速增长的 Claude Code 资源从链接堆变成可维护数据资产 | +| 核心机制 | `THE_RESOURCES_TABLE.csv`、`data/`、`resources/`、`scripts/`、`tests/`、`templates/` | +| 真正带来结果的动作 | 用结构化字段和校验脚本治理资源生命周期 | +| 可迁移做法 | 资源 schema、active/stale/removed 状态、last_checked、license、release 字段 | +| 不可迁移条件 | 不复制 Claude Code 生态分类，不让本仓变成泛 AI 资源大全 | +| 下一步试用动作 | 为 `assets/external-resources/` 建字段契约和过期检查规则 | -## 可借鉴点 +## 改良迭代 -- 资源不应只放 Markdown，应该有表格/数据源、生成脚本和测试。 -- 外部生态索引需要模板和校验来防止链接堆腐烂。 -- 适合对照本仓外部资源注册表的字段和质量门禁。 +| 改良目标 | 原模式 | 本仓版本 | 验证指标 | +|:---|:---|:---|:---| +| 资源事实源 | CSV 主表 | 本地资源注册表 + schema | 每个资源有 id、category、source、status、last_checked | +| 生命周期治理 | active / stale / removed | active、stale、archived、removed | 过期资源能被脚本发现 | +| 展示与治理分离 | templates 生成展示 | README 作为展示，数据文件作为事实源 | README 不再手写漂移 | -## 风险和边界 +## 可迁移清单 -- 生态索引很宽，直接照搬会稀释本仓主线。 -- Claude Code 特有资源需要和 Codex/Cline/Aider 等工具中立视角区分。 -- 资源质量需要按 owner、维护状态和可验证性二次筛选。 +- 明确外部资源字段：ID、名称、分类、链接、作者、许可证、状态、最后检查时间、失效原因。 +- 增加资源生命周期状态，不再只有“存在/不存在”。 +- 把资源展示和资源事实源分离。 +- 用脚本检查重复 ID、缺字段、过期检查和非法分类。 -## 下一轮研究任务 +## 不可迁移清单 -- 研究 `THE_RESOURCES_TABLE.csv` 字段，映射到本仓 `assets/external-resources/` schema。 -- 阅读其 scripts/tests，判断哪些资源校验可复用。 +- 不复制 Claude Code 生态的具体分类体系。 +- 不把所有资源都升级成研究域；只有高价值资源才进入 research。 +- 不在 README 中手写所有资源事实。 + +## 验证动作 + +| 动作 | 成功信号 | 失败信号 | +|:---|:---|:---| +| 抽样 30 条本地资源做 schema 校验 | 能发现缺字段和过期资源 | 仍靠人工肉眼检查 | +| 为资源增加生命周期状态 | stale/removed 能被识别 | 失效资源仍在 active 列表 | +| 生成或校验展示索引 | 展示和事实源一致 | README 与数据源不一致 | ## 沉淀判断 -- 本轮只完成 L1 理解，不直接迁入 concepts、references、workflow 或 skills。 -- 只有经过 L2 源码阅读、实验验证或交叉对照后的结论，才进入稳定层。 \ No newline at end of file +- 稳定结论应进入 `assets/external-resources/`、`assets/AGENTS.md` 和资源校验脚本。 +- 这是 P1 资源治理对标对象，不只是 Claude Code 生态目录。 diff --git a/docs/research/liyupi-ai-guide/analysis.md b/docs/research/liyupi-ai-guide/analysis.md index 3aed737..430ed95 100644 --- a/docs/research/liyupi-ai-guide/analysis.md +++ b/docs/research/liyupi-ai-guide/analysis.md @@ -2,43 +2,62 @@ ## 本轮结论 -- 这是面向中文用户的大型 AI 知识库和产品实践导航，覆盖 AI 编程、工具测评、项目实战和其他 AI 应用。 -- 它的价值在中文传播、学习路径和产品实战材料，不在 coding agent 底层架构。 -- 本仓应借鉴其面向大众的解释方式和项目实战入口，但只吸收与 Vibe Coding 主线相关的部分。 +`liyupi/ai-guide` 的核心价值是中文大众 AI 知识库和产品实践导航。它覆盖 AI 编程、工具测评、 +项目实战、AI 应用和 Vibe Coding 零基础教程，适合观察大众用户如何进入 AI 编程。 + +本仓应该迁移它的“大众解释能力”和“项目实战入口”，但不能迁移其泛 AI 覆盖面。本仓主线仍是 +Vibe Coding、Agent 工作流、技能、资源治理和工程交付。 ## 本地证据 - 研究对象：`liyupi/ai-guide` - 当前研究角色：AI 资源大全与产品实用路线 -- 本轮成熟度：L1 初步理解 - 原始仓库：`raw/repository/` - 原始来源清单：`raw/sources.yml` - 事实摘要：`domain.yml` -## 结构观察 +## 对标拆解 -- 根目录包含 `.vuepress/`、`AI/`、`Vibe Coding 零基础教程/`、`translations/`、`package.json`。 -- README 包含 translations、Vibe Coding 零基础教程、AI 知识库导航、新手入门、AI 编程、AI 工具测评等块。 -- 这是站点型知识库，内容广，目录多。 +| 项 | 内容 | +|:---|:---| +| 参考对象 | `liyupi/ai-guide` | +| 它解决的核心问题 | 让中文大众用户快速找到 AI 学习、工具和项目实践入口 | +| 核心机制 | VuePress 站点、主题目录、Vibe Coding 零基础教程、AI 编程和工具测评入口 | +| 真正带来结果的动作 | 用大众化表达和项目入口降低理解门槛 | +| 可迁移做法 | getting-started 的低门槛表达、项目实战入口、工具测评候选 | +| 不可迁移条件 | 不扩张为泛 AI 百科，不把工具测评直接当采用结论 | +| 下一步试用动作 | 抽取 Vibe Coding 零基础教程和 AI 编程路径做对照表 | -## 可借鉴点 +## 改良迭代 -- 面向非专家的文案和学习路径值得对照本仓 getting-started。 -- 项目实战材料可作为“从教程到成品”的案例来源。 -- 多主题知识库需要导航层清楚区分主线和支线。 +| 改良目标 | 原模式 | 本仓版本 | 验证指标 | +|:---|:---|:---|:---| +| 大众解释 | 面向广泛 AI 用户 | 面向 Vibe Coding 用户降低门槛 | 新手文档少术语、先给例子 | +| 项目实战 | 多类 AI 应用项目 | 聚焦 coding agent、workflow、skills 实战 | 实战入口不偏离主线 | +| 工具导航 | 工具测评和资源导航 | 候选进入资源注册表和研究域 | 工具有状态和风险字段 | -## 风险和边界 +## 可迁移清单 -- 覆盖面太广，容易偏离 Vibe Coding 工程化主线。 -- 内容多为教程和资源，技术结论需要单独验证。 -- 站点型仓库中可能混有翻译、图片和生成内容，需要分层研究。 +- 学习大众化表达方式，降低 getting-started 的术语门槛。 +- 把项目实战作为从教程到交付的桥。 +- 从工具测评中抽取候选资源，但进入本仓前必须结构化治理。 +- 对“泛 AI”内容做范围裁剪，只保留 Vibe Coding 主线相关项。 -## 下一轮研究任务 +## 不可迁移清单 -- 只抽取 `Vibe Coding 零基础教程/` 和 AI 编程相关路径做二轮研究。 -- 对照其项目实战目录，补充本仓实战案例路线。 +- 不把本仓改造成 AI 大全。 +- 不复制站点目录和泛 AI 应用内容。 +- 不直接引用未验证测评作为工具推荐。 + +## 验证动作 + +| 动作 | 成功信号 | 失败信号 | +|:---|:---|:---| +| 抽样重写一段新手解释 | 非程序员能理解目标和下一步 | 仍需要工程背景才能读懂 | +| 抽取项目实战候选 | 候选能映射到 workflow 或 skills | 实战项目与本仓主线无关 | +| 抽样工具测评进入资源表 | 资源字段完整 | 只是复制测评链接 | ## 沉淀判断 -- 本轮只完成 L1 理解，不直接迁入 concepts、references、workflow 或 skills。 -- 只有经过 L2 源码阅读、实验验证或交叉对照后的结论，才进入稳定层。 \ No newline at end of file +- 稳定结论进入 `docs/getting-started/` 和 `assets/external-resources/`。 +- 本研究域保持 P3 中文大众入口观察对象。 diff --git a/docs/research/luzhenqian-ai-coding-lab/analysis.md b/docs/research/luzhenqian-ai-coding-lab/analysis.md index 2dd1411..352c9e5 100644 --- a/docs/research/luzhenqian-ai-coding-lab/analysis.md +++ b/docs/research/luzhenqian-ai-coding-lab/analysis.md @@ -2,43 +2,62 @@ ## 本轮结论 -- 这是项目实验室型仓库，用多个小项目覆盖 AI 编程、agent、chatbot、RAG、creative、skills 等方向。 -- 它的价值在“项目矩阵”而不是单一工具深挖，适合研究如何用案例组织 AI Coding 学习。 -- 本仓可借鉴它的 lab 分类，把教程从概念进一步落到项目样例。 +`luzhenqian/ai-coding-lab` 的核心价值是项目实验室。它用 agent、chatbot、creative、RAG、skills、 +vibe-coding 等目录组织实践项目，适合研究如何把 AI Coding 从概念推进到可运行案例。 + +本仓最应该迁移的是“实践项目作为概念验收层”：概念和方法论如果没有项目验证，很容易变成空话。 ## 本地证据 - 研究对象：`luzhenqian/ai-coding-lab` - 当前研究角色：AI Coding 项目实验室 -- 本轮成熟度：L1 初步理解 - 原始仓库：`raw/repository/` - 原始来源清单：`raw/sources.yml` - 事实摘要：`domain.yml` +- 深度证据：`deep-dive.md` -## 结构观察 +## 对标拆解 -- 根目录包含 `agent/`、`chatbot/`、`creative/`、`rag/`、`skills/`、`vibe-coding/`。 -- README 以项目列表、适合谁、如何使用、推荐工具组织。 -- 目录名直接对应实验方向，便于读者按兴趣进入。 +| 项 | 内容 | +|:---|:---| +| 参考对象 | `luzhenqian/ai-coding-lab` | +| 它解决的核心问题 | 用多个小项目覆盖 AI Coding 的主要实践方向 | +| 核心机制 | `agent/`、`chatbot/`、`creative/`、`rag/`、`skills/`、`vibe-coding/` 项目矩阵 | +| 真正带来结果的动作 | 用项目目录让学习者按方向进入实践 | +| 可迁移做法 | practice/example 层、项目模板、概念到项目的映射 | +| 不可迁移条件 | 不直接采用未验证项目，不把目录名当质量 | +| 下一步试用动作 | 为本仓设计“最小实践项目模板” | -## 可借鉴点 +## 改良迭代 -- 项目实验室可以作为 concepts/references 的验证层。 -- 按 agent、RAG、chatbot、skills、vibe-coding 分组，适合做学习路径分支。 -- 小项目比长文更容易形成可运行反馈。 +| 改良目标 | 原模式 | 本仓版本 | 验证指标 | +|:---|:---|:---|:---| +| 实践矩阵 | 多方向项目目录 | workflow/practice 中按目标组织项目 | 每个项目有目标、运行命令、验收命令 | +| 概念验收 | 项目承接学习 | concepts 后接最小实践 | 概念能被运行或检查 | +| Skill 实验 | `skills/` 目录 | 本仓 skill 有评测和示例 | skill 不只停在说明 | -## 风险和边界 +## 可迁移清单 -- 项目粒度可能不均，不能只看目录名判断质量。 -- 实验室型仓库通常缺少统一质量门禁。 -- 需要逐项目验证是否能运行。 +- 建立最小实践项目模板。 +- 让 agent、RAG、chatbot、skills 等方向对应学习分支。 +- 每个项目必须有前置条件、运行命令、验收命令和常见失败。 +- 将项目作为 L3 沉淀产物的一部分。 -## 下一轮研究任务 +## 不可迁移清单 -- 挑选 `agent/`、`skills/`、`vibe-coding/` 三个方向做二轮源码阅读。 -- 评估哪些项目可转化为本仓实战示例。 +- 不复制项目代码。 +- 不把实验室当作生产模板。 +- 不新增 practice 层前先无限扩张目录；先用最小模板验证。 + +## 验证动作 + +| 动作 | 成功信号 | 失败信号 | +|:---|:---|:---| +| 设计一个最小实践项目模板 | 模板能指导新项目落地 | 只有项目标题无运行命令 | +| 抽样一个概念映射到练习 | 用户能通过练习验证概念 | 概念仍只能阅读 | +| 抽样一个 skill 增加示例 | 示例能复现 skill 行为 | skill 无法验证 | ## 沉淀判断 -- 本轮只完成 L1 理解，不直接迁入 concepts、references、workflow 或 skills。 -- 只有经过 L2 源码阅读、实验验证或交叉对照后的结论，才进入稳定层。 \ No newline at end of file +- 稳定结论进入 `docs/workflow/`，后续可引出独立 practice/examples 层。 +- 本研究域保持 P2 实践项目对标对象。 diff --git a/docs/research/openai-codex/analysis.md b/docs/research/openai-codex/analysis.md index c1a468d..e5fd51a 100644 --- a/docs/research/openai-codex/analysis.md +++ b/docs/research/openai-codex/analysis.md @@ -2,43 +2,64 @@ ## 本轮结论 -- OpenAI Codex 是官方 terminal coding agent 源码，属于 P1 核心研究对象。 -- 仓库采用 Rust core、CLI、SDK、docs、Bazel/Nix/PNPM 等多工具组合，体现了生产级 agent 工具链的复杂度。 -- 本仓应重点研究其权限、沙箱、命令执行、AGENTS.md 读取、CLI 分发和 SDK 边界。 +`openai/codex` 的核心价值不是“官方 CLI 怎么写”，而是展示了成熟 coding agent 必须有执行控制面。 +它把配置、沙箱、执行策略、工具、技能、项目上下文和交互入口拆成显式对象，避免让高风险行为只靠 +提示词自觉。 + +本仓最应该迁移的是治理思想：凡是能执行命令、改文件、访问网络或影响仓库状态的入口，都必须有 +owner、风险等级、输入输出、dry-run、CI 状态和审计边界。 ## 本地证据 - 研究对象：`openai/codex` - 当前研究角色：官方 coding agent 工具源码 -- 本轮成熟度：L1 初步理解 - 原始仓库：`raw/repository/` - 原始来源清单：`raw/sources.yml` - 事实摘要：`domain.yml` +- 深度证据：`deep-dive.md` -## 结构观察 +## 对标拆解 -- 根目录包含 `codex-rs/`、`codex-cli/`、`sdk/`、`docs/`、`AGENTS.md`、`justfile`、`package.json`、`pnpm-workspace.yaml`、`BUILD.bazel`。 -- README 聚焦 Codex CLI 安装、运行和 Docs 入口。 -- 存在 `.codex/`、`.devcontainer/`、Bazel、Nix 等开发环境和构建基础设施。 +| 项 | 内容 | +|:---|:---| +| 参考对象 | `openai/codex` | +| 它解决的核心问题 | 让本地 coding agent 的命令执行、文件修改和工具调用进入可配置、可审计、可限制的系统 | +| 核心机制 | `config`、`sandboxing`、`linux-sandbox`、`tools`、`skills`、`docs/exec*`、`AGENTS.md` 分层 | +| 真正带来结果的动作 | 把执行风险做成系统对象，而不是把风险控制写成提示词愿望 | +| 可迁移做法 | 脚本登记表、风险等级、自动执行边界、人工审批边界、dry-run 和审计说明 | +| 不可迁移条件 | 不复制 Rust workspace、Bazel/Nix、CLI runtime 和产品级沙箱实现 | +| 下一步试用动作 | 先为本仓 `scripts/` 建立 `manifest.yml` 或等价登记表 | -## 可借鉴点 +## 改良迭代 -- 官方 agent 工具把本地运行、权限边界、CLI 交互和项目规则文件作为核心能力。 -- Rust core + CLI 包装适合研究高可靠本地工具的工程形态。 -- `AGENTS.md` 作为项目规则入口与本仓方向高度一致。 +| 改良目标 | 原模式 | 本仓版本 | 验证指标 | +|:---|:---|:---|:---| +| 脚本控制面 | Codex 将执行策略和沙箱显式化 | `scripts/manifest.yml` 记录脚本 owner、风险、输入、输出、CI 状态 | Agent 能判断哪些脚本可自动执行，哪些必须人工确认 | +| Agent 上下文接口 | Codex 使用 `AGENTS.md` 承载项目规则 | 保持根目录和子目录 `AGENTS.md` 为正式上下文入口 | 新目录或架构变更后索引和 AGENTS 同步 | +| 技能治理 | Codex 将 skills 作为可复用能力对象 | 本仓 skills 必须有触发条件、边界、输入输出和验证 | skill 不再只是 prompt 收藏 | -## 风险和边界 +## 可迁移清单 -- 官方产品快速演进，结论容易过期。 -- 仓库构建系统复杂，不能只读 README 下结论。 -- 需要区分 Codex CLI、本地 app、Web/Cloud Codex 等产品边界。 +- 对所有写仓库、网络访问、高风险发布或迁移脚本标注风险等级。 +- 对脚本补齐输入、输出、幂等性、dry-run、失败恢复和审计说明。 +- 把 Agent 可自动执行与必须人工确认的边界写进 `scripts/AGENTS.md`。 +- 把命令执行策略沉淀到 `docs/references/` 或 `docs/workflow/`。 -## 下一轮研究任务 +## 不可迁移清单 -- 重点阅读 `codex-rs/` 中命令执行、sandbox、approval、config、project docs 相关代码。 -- 整理 Codex 的本地 agent safety model 到 references。 +- 不把本仓改造成 Codex 类 runtime 产品。 +- 不为了“看起来企业级”引入复杂沙箱、Bazel、Nix 或多语言构建系统。 +- 不把官方产品实现等同于本仓必须采用的唯一标准。 + +## 验证动作 + +| 动作 | 成功信号 | 失败信号 | +|:---|:---|:---| +| 抽样 5 个 `scripts/` 文件登记 owner、风险、输入输出 | 维护者能一眼判断脚本能否自动跑 | 仍需要读源码才知道脚本风险 | +| 给写仓库脚本补 dry-run 或说明为何不能 dry-run | 高风险动作有预演或审计路径 | 脚本一运行就产生不可逆副作用 | +| 把脚本风险边界加入 `scripts/AGENTS.md` | Agent 执行前能引用明确规则 | 每次仍靠对话临时判断 | ## 沉淀判断 -- 本轮只完成 L1 理解，不直接迁入 concepts、references、workflow 或 skills。 -- 只有经过 L2 源码阅读、实验验证或交叉对照后的结论，才进入稳定层。 \ No newline at end of file +- 稳定结论应下沉到 `scripts/`、`docs/workflow/` 和 `docs/references/`。 +- `deep-dive.md` 保留源码证据；本文件负责把证据转成迁移动作。 diff --git a/docs/research/research-domain-contract.md b/docs/research/research-domain-contract.md index 4186508..5b9ecbc 100644 --- a/docs/research/research-domain-contract.md +++ b/docs/research/research-domain-contract.md @@ -43,6 +43,27 @@ 动态事实不能写死成永久结论。stars、forks、release、归档状态、维护活跃度、许可证和默认分支等字段只代表观测日快照。 +### 研究必须可迁移 + +研究域不能停在“这个对象是什么”。进入 L1 以后，研究必须继续回答： + +- 它为什么能产生结果。 +- 哪些机制是真正有效部分。 +- 哪些做法可以迁移到本仓。 +- 哪些条件不能迁移，不能照搬。 +- 本仓应该如何改良成自己的版本。 +- 用什么最小动作验证迁移是否有效。 + +深度研究必须遵循“对标拆解 -> 改良迭代 -> 杂交创新”的转化链： + +| 方法 | 研究问题 | 必备输出 | +|:---|:---|:---| +| 对标拆解 | 成熟对象为什么有效 | 参考对象、核心机制、可迁移做法、不可迁移条件、下一步试用动作 | +| 改良迭代 | 这个机制怎样适配本仓 | 改动点、验证指标、反馈信号和下一轮方向 | +| 杂交创新 | 多个成熟机制如何组合 | 来源机制、组合逻辑、适用条件、风险点和验证指标 | + +如果一篇研究读完以后不能指导用户下一步行动，它还只是资料整理，不能算 L2 深度研究。 + ## 标准目录结构 每个长期研究域的推荐结构如下： @@ -73,6 +94,7 @@ - 研究对象和研究角色。 - 当前优先级。 - 当前判断。 +- 用户读完能拿走什么。 - 关键观察字段。 - 后续观察点。 @@ -175,6 +197,23 @@ python3 scripts/fetch-research-raw.py openai/codex raw 层拉取成功后，再把稳定事实摘要同步到 `domain.yml`；不要直接从记忆或二手总结更新 `domain.yml`。 +### analysis.md + +`analysis.md` 是迁移层，不是普通摘要。它必须把事实和判断转成可执行研究结论。 + +P1/P2 研究域的 `analysis.md` 必须包含： + +- 本轮结论。 +- 本地证据。 +- 对标拆解。 +- 改良迭代。 +- 可迁移清单。 +- 不可迁移清单。 +- 验证动作。 +- 沉淀判断。 + +其中“验证动作”必须同时写成功信号和失败信号，避免研究结论不可证伪。 + ## 成熟度分级 研究域按成熟度推进，不要求一次写满。 @@ -182,8 +221,8 @@ raw 层拉取成功后，再把稳定事实摘要同步到 `domain.yml`；不要 | 级别 | 名称 | 必备产物 | 判断标准 | |:---|:---|:---|:---| | L0 | 登记 | `README.md`、`AGENTS.md`、`domain.yml`、`raw/` | 对象身份清楚，原始材料已拉取到本地且来源可复查 | -| L1 | 理解 | `analysis.md` | 能解释架构、工作流、适用场景和风险 | -| L2 | 验证 | `deep-dive.md`、`experiments/` 或可复现验证记录 | 关键判断经过源码阅读、本地实验或一手资料核验 | +| L1 | 理解 | `analysis.md` | 能解释架构、工作流、适用场景、风险和初步迁移方向 | +| L2 | 验证 | `deep-dive.md`、`experiments/` 或可复现验证记录 | 关键判断经过源码阅读、本地实验或一手资料核验，并能产出对标拆解、迁移边界和验证动作 | | L3 | 沉淀 | 下游 concepts / references / workflow / skills 文档 | 研究结论已经变成稳定方法、模板、流程或技能 | | L4 | 归档 | `archive/` 或归档说明 | 对象失效、被替代、已归档或不再值得跟踪 | @@ -209,6 +248,7 @@ raw 层拉取成功后，再把稳定事实摘要同步到 `domain.yml`；不要 - `docs/research/README.md` 的索引判断中。 - 新增的独立对比文档中。 +- `research-transfer-synthesis.md` 这样的迁移综合文档中。 - 成熟后迁入 `docs/references/` 或 `docs/concepts/`。 禁止为了比较方便把多个研究对象塞回同一个目录。 @@ -233,6 +273,7 @@ raw 层拉取成功后，再把稳定事实摘要同步到 `domain.yml`；不要 - 是否存在 `README.md`、`AGENTS.md`、`domain.yml` 和 `raw/`。 - `raw/` 是否存在 `README.md`、`AGENTS.md`、`sources.yml`、`repository/` 和至少一个原始材料文件。 - 是否区分原始事实、事实摘要、判断、假设和决策。 +- `analysis.md` 是否包含对标拆解、改良迭代、可迁移清单、不可迁移清单和验证动作。 - 动态事实是否有 `observed_at`、来源、核验方式和本地 raw 依据。 - 是否避免复制外部项目全文。 - 是否更新所有索引和机器可读入口。 diff --git a/docs/research/research-transfer-synthesis.md b/docs/research/research-transfer-synthesis.md new file mode 100644 index 0000000..a9c119a --- /dev/null +++ b/docs/research/research-transfer-synthesis.md @@ -0,0 +1,138 @@ +# 研究迁移综合 + +## 字多不看 + +- 研究不是证明“我看过资料”，而是把成熟对象拆成可迁移机制、不可迁移边界和可验证动作。 +- 本轮把 P1 研究对象合成为一条主线：Codex 负责执行控制面，Aider 负责 Git 编辑闭环，Cline 负责多入口平台化，Claude Code Best Practice 负责方法论资产化。 +- 本仓不应该复制任何一个外部项目，而应该杂交成“AI 原生知识库控制面”。 +- 下一步最小试用动作是：补 `scripts` 风险登记、补研究域迁移表、补资源治理 schema、补工作流验证闭环。 + +## 研究质量问题 + +上一版研究读起来没有收获，根因不是材料不足，而是研究链条断在“观察”阶段： + +| 缺口 | 表现 | 修正方式 | +|:---|:---|:---| +| 机制不足 | 只写目录结构和可借鉴点 | 明确哪个机制真正制造结果 | +| 迁移不足 | 只说“本仓可参考” | 写清能迁移什么、不能迁移什么 | +| 动作不足 | 只写“下一轮研究” | 写出下一步试用动作和验收指标 | +| 组合不足 | 单个仓库各说各话 | 把多个机制组合成本仓可执行方案 | +| 验证不足 | 结论像观点 | 给出证据来源、试用指标和失败条件 | + +新的研究标准是： + +> 每个深度研究必须回答：它为什么有效，我能抄哪里，不能抄哪里，怎么改成本仓版本，如何验证改完真的更好。 + +## 对标拆解 + +| 参考对象 | 核心机制 | 真正带来结果的动作 | 可迁移做法 | 不可迁移条件 | 下一步试用动作 | +|:---|:---|:---|:---|:---|:---| +| `openai/codex` | 执行控制面 | 把配置、沙箱、执行策略、工具、技能和项目上下文显式建模 | `scripts` 风险分级、Agent 执行边界、技能输入输出契约 | 不复制 Rust/Bazel/CLI runtime，本仓不是 coding agent 产品 | 建立 `scripts/manifest.yml`，记录 owner、风险、输入、输出、dry-run 和 CI 状态 | +| `Aider-AI/aider` | Git 驱动编辑闭环 | 让每次 AI 修改都进入 diff、lint/test、commit、回滚和审查链路 | 研究域和文档修改必须保留 diff 证据、门禁命令和失败修复记录 | 不复制 Python 实现、repo map 算法和完整交互式终端产品 | 建立“AI 修改 -> diff 审查 -> make test -> commit”工作流模板 | +| `cline/cline` | 多入口 agent 平台 | 同一套能力暴露为 IDE、CLI、SDK、rules、skills、examples 和测试平台 | 为人类入口、AI 入口、脚本入口、skill 入口、资源入口和 metadata 入口写清协议 | 不提前做 SDK、服务端 hub 或复杂 UI | 梳理本仓入口矩阵，记录每个入口的输入、输出、owner 和验证命令 | +| `shanraisshan/claude-code-best-practice` | 方法论资产化 | 把经验拆成 best practice、implementation、workflow、reports、config | 把经验短句下沉为概念、模板、流程、skill 或检查项 | 不照搬 Claude Code 生态绑定配置，不把个人偏好当通用标准 | 建立“经验 -> 产物类型 -> 验证方式”的分流表 | +| `hesreallyhim/awesome-claude-code` | 资源治理系统 | 用结构化主表、状态字段、脚本、测试和模板治理外部资源 | 外部资源本地化、生命周期字段、去重和失效检查 | 不复制其分类体系，本仓聚焦中文 Vibe Coding | 为 `assets/external-resources` 增加字段契约和过期检查策略 | +| `tradecatlabs/vibe-coding-cn` | AI 原生知识库雏形 | 把 docs、skills、scripts、metadata、assets、research 和 llms 入口工程化 | 用外部样本反向校准本仓，持续把研究下沉到稳定层 | 不因自我研究陷入自我确认 | 对 P1 研究结论做跨对象组合和下游落地 | + +## 全量研究域迁移矩阵 + +| 研究域 | 类型 | 最有价值机制 | 本仓迁移位置 | 下一步动作 | +|:---|:---|:---|:---|:---| +| `openai-codex` | coding-agent-tooling | 执行控制面 | `scripts/`、`workflow/`、`references/` | 建脚本风险登记表 | +| `aider-ai-aider` | coding-agent-tooling | Git 驱动编辑闭环 | `workflow/` | 建 AI 修改到提交的证据模板 | +| `cline-cline` | coding-agent-tooling | 多入口 agent 平台 | `metadata/`、`llms.txt`、`skills/` | 建入口矩阵 | +| `shanraisshan-claude-code-best-practice` | agentic-engineering-methodology | 方法论资产化 | `concepts/`、`workflow/`、`skills/` | 建经验分流表 | +| `hesreallyhim-awesome-claude-code` | ecosystem-index | 资源治理系统 | `assets/external-resources/` | 强化资源 schema | +| `tradecatlabs-vibe-coding-cn` | workflow-methodology | AI 原生知识库控制面 | 全仓 | 建自我审计和下沉任务 | +| `datawhalechina-easy-vibe` | cn-onboarding | 目标分流课程路径 | `getting-started/` | 重构学习地图分流 | +| `datawhalechina-vibe-vibe` | cn-onboarding | demo 驱动零基础课程 | `getting-started/`、未来 practice | 给概念补最小练习 | +| `liyupi-ai-guide` | cn-onboarding | 大众解释和项目实战入口 | `getting-started/`、`assets/` | 抽取低门槛表达和工具候选 | +| `wendy7756-vibe-coding-guide` | cn-onboarding | 非程序员视角 | `getting-started/`、`prompts/` | 增加非程序员入口说明 | +| `luzhenqian-ai-coding-lab` | project-practice | 项目实验室矩阵 | `workflow/`、未来 practice | 建最小实践项目模板 | +| `shouzhengai-cs146s-cn` | project-practice | assignments 验证层 | `getting-started/`、`workflow/` | 建练习任务模板 | +| `filipecalegario-awesome-vibe-coding` | ecosystem-index | 国际工具族和术语雷达 | `assets/`、`concepts/keyword-system.md` | 抽取工具族和术语对照 | +| `ai-for-developers-awesome-vibe-coding` | ecosystem-index | 轻量工具分类雷达 | `assets/external-resources/` | 对照资源分类缺口 | +| `daotin-ai-coding` | workflow-methodology | 中文 AI Coding 主题雷达 | `concepts/keyword-system.md`、`assets/` | 抽取中文高频主题 | +| `earyantle-vibe-coding-skill` | workflow-methodology | 最小 Skill 骨架 | `skills/` | 建 Skill 发布检查清单 | +| `roocodeinc-roo-code` | coding-agent-tooling | 归档工具生命周期样本 | `research/`、`assets/` | 明确 archived 降级规则 | + +## 改良迭代 + +### 第一轮：让研究从“结论”变成“动作” + +目标结果：用户打开研究文档后，能直接知道下一步怎么改自己的仓库。 + +| 改动点 | 原模式 | 本仓改良 | 验证指标 | +|:---|:---|:---|:---| +| 研究域分析 | 结构观察和可借鉴点 | 对标拆解、迁移边界、试用动作 | 17 个研究域 `analysis.md` 都有可执行动作 | +| 深度研究 | L2 证据和关键机制 | 保留证据链，另写迁移综合 | 证据和行动分层清楚 | +| 价值地图 | 用户价值说明 | 增加组合方案和验收指标 | 能回答“看完有什么用” | + +### 第二轮：让研究进入仓库控制面 + +目标结果：研究结论不再停在 research，而是进入 `scripts`、`workflow`、`assets`、`skills` 和 `references`。 + +| 迁移方向 | 来源机制 | 本仓目标产物 | 验证指标 | +|:---|:---|:---|:---| +| `scripts` 控制面 | Codex exec policy / sandbox | 脚本登记表、风险等级、dry-run 和审批边界 | 每个脚本有 owner、风险、输入输出和 CI 状态 | +| Git 编辑闭环 | Aider repo editing loop | AI 修改工作流和提交前证据模板 | 每次提交说明验证命令和 diff 范围 | +| 多入口契约 | Cline IDE / CLI / SDK / rules | 人类入口、AI 入口、脚本入口、skill 入口矩阵 | 每个入口有输入、输出、更新策略 | +| 方法论分流 | Claude best practice | 经验到 concepts/references/workflow/skills 的分流规则 | 经验短句不再孤立堆放 | +| 资源治理 | awesome-claude-code CSV | 资源 schema、状态字段、过期检查 | 资源表能被脚本校验 | + +### 第三轮：让研究可以被证伪 + +目标结果：研究不再是“写得像对”，而是能通过小实验判断是否有效。 + +| 假设 | 最小实验 | 成功信号 | 失败信号 | +|:---|:---|:---|:---| +| `scripts` manifest 能降低脚本风险 | 选 5 个脚本补 owner、风险、输入输出和自动执行边界 | Agent 能判断哪些脚本可自动跑 | 仍需要人工逐个解释脚本用途 | +| 文档地图能降低索引漂移 | 为 research 建生成或校验入口 | README、metadata、llms 路径一致 | 新文档漏进索引 | +| 资源 schema 能提升资源质量 | 抽样 30 条资源做字段校验 | 能发现缺 license、last_checked 或重复 ID | 仍靠肉眼维护 | +| 经验分流能提升学习效果 | 将 10 条经验分别落到概念、流程或 skill | 用户能按目的找到对应动作 | 经验仍只是口号 | + +## 杂交创新 + +本仓最优路线不是学习某一个外部仓库，而是把多个成熟机制组合成一个更适合中文 Vibe Coding 的系统： + +```text +AI 原生知识库控制面 +├── research/ # 发现和验证外部机制 +├── assets/ # 治理外部资源和引用材料 +├── metadata/ # 提供机器可读索引 +├── scripts/ # 执行质量门禁和同步任务 +├── workflow/ # 约束 AI 修改、验证和交付过程 +├── skills/ # 沉淀可复用 Agent 能力 +└── docs/ # 面向人类的稳定知识层 +``` + +组合逻辑： + +- Codex 给出“执行必须有控制面”的底线。 +- Aider 给出“修改必须进入 Git 和测试闭环”的底线。 +- Cline 给出“入口必须平台化和契约化”的方向。 +- Claude Code Best Practice 给出“方法论必须文件系统化”的方向。 +- Awesome 生态给出“资源必须结构化治理”的方向。 +- 本仓负责把这些机制压成中文学习路径、工程模板和 Agent 可执行规则。 + +## 下一步落地清单 + +| 优先级 | 动作 | 目标位置 | 完成标准 | +|:---|:---|:---|:---| +| P0 | 更新 P1 研究域 `analysis.md` | `docs/research/*/analysis.md` | 每个样板有对标拆解、改良迭代和试用动作 | +| P0 | 升级研究域治理契约 | `docs/research/research-domain-contract.md` | L2/L3 明确要求迁移动作和验证指标 | +| P1 | 建立 scripts 控制面 | `scripts/` | manifest、风险等级、自动/人工边界 | +| P1 | 建立入口矩阵 | `docs/references/` 或 `docs/workflow/` | 人类、AI、脚本、skill、资源入口边界清楚 | +| P1 | 建立资源 schema | `assets/external-resources/` | 字段、生命周期、过期检查和去重规则 | +| P2 | 建立经验分流规则 | `docs/getting-started/`、`docs/workflow/`、`skills/` | 经验短句能下沉成可执行产物 | + +## 验收标准 + +研究文档以后必须满足以下标准，否则就只是资料整理： + +- 能说清参考对象的核心机制。 +- 能指出哪些机制真正带来结果。 +- 能列出可迁移做法和不可迁移条件。 +- 能给出本仓改良版本，而不是照搬原模式。 +- 能给出最小试用动作和验证指标。 +- 能说明失败信号，允许研究结论被证伪。 diff --git a/docs/research/research-value-application-map.md b/docs/research/research-value-application-map.md index a344ea5..9d9920a 100644 --- a/docs/research/research-value-application-map.md +++ b/docs/research/research-value-application-map.md @@ -3,10 +3,12 @@ ## 字多不看 - 当前研究体系已经覆盖 17 个独立研究域，其中 11 个完成 L2 深度研究。 -- 这些研究不是为了介绍外部项目，而是为了把外部项目拆成可验证事实、可迁移模式和本仓可执行改进项。 +- 这些研究不是为了介绍外部项目，而是为了把外部项目拆成可验证事实、核心机制、迁移边界和本仓可执行改进项。 +- 17 个研究域的 `analysis.md` 已统一为对标拆解、改良迭代、可迁移清单、不可迁移清单和验证动作格式。 - 用户获得的直接价值是少走弯路、看见范式、拿到可落地路线。 - 本仓获得的直接价值是形成 `getting-started`、`references`、`workflow`、`skills`、`assets`、`scripts` 和 `research` 的改进输入。 +- 新增的 [研究迁移综合](research-transfer-synthesis.md) 专门回答“这些研究怎么变成可执行动作”。 - 研究结论稳定后必须下沉，不应长期停在 research。 ## 当前覆盖 @@ -19,6 +21,21 @@ ## 用户能获得什么 +### 研究到行动 + +用户不应该只看到“这个仓库值得研究”。每个 P1/P2 研究对象都应该进一步提供： + +- 对标拆解：成熟对象为什么有效。 +- 改良迭代：本仓应该如何改成自己的版本。 +- 杂交创新：多个对象的有效机制如何组合。 +- 验证指标：下一步动作怎样判断成功或失败。 + +因此，研究阅读顺序应调整为： + +1. 先读单个研究域的 `analysis.md`，拿到可迁移动作。 +2. 再读 `deep-dive.md`，确认动作背后的证据。 +3. 最后读 [研究迁移综合](research-transfer-synthesis.md)，理解多个对象如何组合成本仓路线。 + ### 少走弯路 用户不需要自己从大量仓库里判断哪些值得学、哪些只是资源堆、哪些适合照搬、哪些只能参考。 diff --git a/docs/research/roocodeinc-roo-code/analysis.md b/docs/research/roocodeinc-roo-code/analysis.md index e742efa..7491c2d 100644 --- a/docs/research/roocodeinc-roo-code/analysis.md +++ b/docs/research/roocodeinc-roo-code/analysis.md @@ -2,43 +2,61 @@ ## 本轮结论 -- Roo Code 是已归档的多模式编辑器 agent 工具，当前更适合作为设计参考和历史样本。 -- 虽然归档，但其 monorepo 结构、modes、schemas、webview-ui、packages 和 src 仍有研究价值。 -- 本仓应借鉴它的模式配置、扩展 UI 与 agent 工具组织，但不应把它列为优先采用对象。 +`RooCodeInc/Roo-Code` 当前已归档，因此它的价值不是采用，而是生命周期和模式设计参考。它仍保留 +多模式、schema、webview UI、packages 和 monorepo 结构，适合研究 IDE agent 的历史设计和归档降级策略。 + +本仓最应该迁移的是“归档不等于删除”：归档对象应从采用候选降级为历史样本，保留可复用机制，移除采用暗示。 ## 本地证据 - 研究对象：`RooCodeInc/Roo-Code` - 当前研究角色：已归档多 Agent 编辑器工具 -- 本轮成熟度：L1 初步理解 - 原始仓库：`raw/repository/` - 原始来源清单：`raw/sources.yml` - 事实摘要：`domain.yml` -## 结构观察 +## 对标拆解 -- 根目录包含 `apps/`、`packages/`、`src/`、`webview-ui/`、`schemas/`、`locales/`、`.roo/`、`.roomodes`。 -- README 以 What Can Roo Code Do、Modes、Resources、Disclaimer、License 组织。 -- 存在 pnpm workspace、turbo、changeset 等前端/扩展 monorepo 基础设施。 +| 项 | 内容 | +|:---|:---| +| 参考对象 | `RooCodeInc/Roo-Code` | +| 它解决的核心问题 | 曾经尝试用多模式和编辑器 UI 承载 agent 编程工作流 | +| 核心机制 | `apps/`、`packages/`、`src/`、`webview-ui/`、`schemas/`、`.roomodes` | +| 真正带来结果的动作 | 用显式模式和 schema 管理 agent 行为差异 | +| 可迁移做法 | 模式文件、schema 约束、归档对象降级策略 | +| 不可迁移条件 | 已归档，不作为活跃采用对象，不跟随其生态路线 | +| 下一步试用动作 | 在研究域治理中明确 archived 对象的降级规则 | -## 可借鉴点 +## 改良迭代 -- 多模式 agent 可以通过显式模式文件和 schema 管理。 -- Webview UI 与扩展核心分离是 IDE agent 的常见形态。 -- 归档项目仍可作为迁移风险和生态生命周期样本。 +| 改良目标 | 原模式 | 本仓版本 | 验证指标 | +|:---|:---|:---|:---| +| 生命周期治理 | 归档仓库仍可阅读 | 本仓标记 archived / low-frequency reference | 用户不会误以为推荐采用 | +| 模式设计 | `.roomodes` 和 schema | 本仓 agent 模式或 skill 模式需要 schema 思维 | 模式有输入、输出、边界 | +| 风险降级 | 历史项目继续被引用 | 引用时标注归档状态和替代对象 | 归档对象不进入 P1 采用清单 | -## 风险和边界 +## 可迁移清单 -- `domain.yml` 已标记 archived，不能当作活跃生态主线。 -- 历史实现可能已经被 fork 或替代，采用建议必须重新核验。 -- 仓库体量较大，二轮研究要聚焦模式和 schema，不做全量阅读。 +- 为归档研究对象写明状态、用途和替代对象。 +- 从历史项目中只抽机制，不抽采用建议。 +- 研究模式/schema 如何约束 agent 行为。 +- 在资源表中对 archived/stale 资源做可见标记。 -## 下一轮研究任务 +## 不可迁移清单 -- 阅读 `.roomodes`、`schemas/` 和 `src/` 中 mode/tool 相关代码。 -- 整理“归档工具如何降级为参考对象”的研究归档规则。 +- 不推荐用户采用已归档项目。 +- 不把归档前的生态热度当作当前价值。 +- 不复制其 monorepo 和 UI 结构。 + +## 验证动作 + +| 动作 | 成功信号 | 失败信号 | +|:---|:---|:---| +| 检查所有 archived 资源标记 | 归档状态在索引可见 | 用户仍看不出对象已归档 | +| 抽取一个模式/schema 机制 | 能转成通用模式设计说明 | 只停留在目录观察 | +| 为归档对象写替代建议 | 有活跃替代对象或降级说明 | 仍像推荐对象 | ## 沉淀判断 -- 本轮只完成 L1 理解，不直接迁入 concepts、references、workflow 或 skills。 -- 只有经过 L2 源码阅读、实验验证或交叉对照后的结论，才进入稳定层。 \ No newline at end of file +- 稳定结论进入研究域治理契约和资源生命周期字段。 +- 本研究域保持 P3 归档历史样本。 diff --git a/docs/research/shanraisshan-claude-code-best-practice/analysis.md b/docs/research/shanraisshan-claude-code-best-practice/analysis.md index c43138a..4bb11ae 100644 --- a/docs/research/shanraisshan-claude-code-best-practice/analysis.md +++ b/docs/research/shanraisshan-claude-code-best-practice/analysis.md @@ -2,43 +2,64 @@ ## 本轮结论 -- 这是 Agentic Engineering 方法论和 Claude Code 资产集合，属于 P1 对标对象。 -- 它覆盖 concepts、development workflows、cross-model workflows、skill collections、agent collections、tips、orchestration 等层。 -- 本仓应重点吸收其 agent/team/workflow/skill 的组织方式，同时保持本仓自己的中文主线和质量门禁。 +`shanraisshan/claude-code-best-practice` 的核心价值不是“Claude Code 资料多”，而是展示了方法论如何 +变成文件系统、配置、workflow、reports 和 agent teams。它说明经验如果不能落到文件、流程、 +示例或检查项，就只是口号。 + +本仓最应该迁移的是方法论资产化：把经验短句分流到 concepts、references、workflow、skills、 +research 或 reports，而不是长期堆在一个经验清单里。 ## 本地证据 - 研究对象：`shanraisshan/claude-code-best-practice` - 当前研究角色：Claude Code / Agentic Engineering 最强对标 -- 本轮成熟度：L1 初步理解 - 原始仓库：`raw/repository/` - 原始来源清单：`raw/sources.yml` - 事实摘要：`domain.yml` +- 深度证据：`deep-dive.md` -## 结构观察 +## 对标拆解 -- 根目录包含 `best-practice/`、`development-workflows/`、`orchestration-workflow/`、`agent-teams/`、`implementation/`、`tips/`、`tutorial/`、`reports/`。 -- 存在 `.claude/`、`.codex/`、`.mcp.json`、`CLAUDE.md`，说明它同时面向多个 AI 工具运行环境。 -- README 是大型导航页，入口多、概念密度高。 +| 项 | 内容 | +|:---|:---| +| 参考对象 | `shanraisshan/claude-code-best-practice` | +| 它解决的核心问题 | 把 Claude Code / Agentic Engineering 经验变成可复用操作资产 | +| 核心机制 | `best-practice/` 放原则，`implementation/` 放实现，`orchestration-workflow/` 放流程，`reports/` 放复盘，配置文件放运行入口 | +| 真正带来结果的动作 | 让方法论进入文件、配置、示例、报告和工作流，而不是停留在聊天记录 | +| 可迁移做法 | 经验分流、agent teams 契约、harness 报告、配置治理、报告层沉淀 | +| 不可迁移条件 | 不照搬 Claude 生态绑定配置，不把个人实践当通用事实 | +| 下一步试用动作 | 建立“经验 -> 产物类型 -> 验证方式”的分流表 | -## 可借鉴点 +## 改良迭代 -- Agentic Engineering 需要把 workflow、agent team、skills、commands、MCP、tips 分层管理。 -- 跨模型/跨工具工作流应该作为研究对象，而不是只绑定某一个产品。 -- 大型方法论仓库需要强导航，否则会变成资料迷宫。 +| 改良目标 | 原模式 | 本仓版本 | 验证指标 | +|:---|:---|:---|:---| +| 方法论分流 | best-practice / implementation / workflow / reports 分层 | concepts / references / workflow / skills / research 分层 | 每条经验能找到落点 | +| 复杂任务编排 | agent teams 和 orchestration workflow | 本仓任务树、子 Agent、tmux 协作和验收标准 | 多 Agent 任务有职责、输入、输出、依赖、验收 | +| 报告层沉淀 | reports 承载复盘和比较 | 本仓 research 和 references 承载阶段判断 | 重要结论不只留在对话里 | -## 风险和边界 +## 可迁移清单 -- 内容高度个人化，不能直接变成本仓标准。 -- 覆盖面很宽，容易冲淡本仓“Vibe Coding 中文教程 + 工程治理”的定位。 -- 需要区分 Claude Code 专属实践和通用 agent engineering 原则。 +- 对经验短句做分流：概念、模板、流程、skill、检查项、归档。 +- 对复杂研究任务写清角色、输入、输出、依赖和验收标准。 +- 对重要失败或纠偏产出独立报告，避免同类问题反复出现。 +- 把 hooks、settings、MCP、skills 等配置视为 AI 工程系统的一部分，而不是私人工具偏好。 -## 下一轮研究任务 +## 不可迁移清单 -- 重点拆读 `orchestration-workflow/`、`agent-teams/`、`development-workflows/`。 -- 输出与本仓 `skills/`、`workflow/`、`research-domain-contract.md` 的差距清单。 +- 不把 Claude Code 专属配置当作所有 Agent 的通用标准。 +- 不直接复制命名结构；本仓已有 docs、skills、scripts、assets、metadata，需要按自身结构吸收。 +- 不把未经验证的个人经验写成硬规则。 + +## 验证动作 + +| 动作 | 成功信号 | 失败信号 | +|:---|:---|:---| +| 抽样 10 条经验做分流 | 每条经验进入概念、流程、模板或 skill | 经验仍只是短句 | +| 为一次复杂研究任务写 agent teams 契约 | 子任务边界清楚、可验收 | 多 Agent 只是并行堆上下文 | +| 把一次失败研究写成复盘规则 | 同类失败有前置检查 | 下次继续产出空泛研究 | ## 沉淀判断 -- 本轮只完成 L1 理解，不直接迁入 concepts、references、workflow 或 skills。 -- 只有经过 L2 源码阅读、实验验证或交叉对照后的结论，才进入稳定层。 \ No newline at end of file +- 稳定结论应下沉到 `docs/getting-started/`、`docs/workflow/`、`docs/references/` 和 `skills/`。 +- `deep-dive.md` 保留证据；本文件负责把证据转成迁移动作。 diff --git a/docs/research/shouzhengai-cs146s-cn/analysis.md b/docs/research/shouzhengai-cs146s-cn/analysis.md index ff5a8f0..aa90d35 100644 --- a/docs/research/shouzhengai-cs146s-cn/analysis.md +++ b/docs/research/shouzhengai-cs146s-cn/analysis.md @@ -2,43 +2,62 @@ ## 本轮结论 -- 这是课程型仓库，价值在教学大纲、周次安排和 assignments，而不是工具实现。 -- 它把 coding LLM、coding agent、AI IDE、agent 模式、现代终端、测试安全、软件支持和 UI 自动化放进课程周次。 -- 本仓可借鉴其课程化节奏，把入门、工具、agent 模式、测试安全和自动化分阶段讲清。 +`ShouZhengAI/CS146S_CN` 的核心价值是课程化和 assignments。它把 coding LLM、coding agent、AI IDE、 +agent 模式、现代终端、测试安全、软件支持和 UI 自动化放进周次节奏，并用作业承接学习。 + +本仓最应该迁移的是“作业作为验证层”：学习路径不能只给阅读材料，还要给可提交、可检查、可反馈的任务。 ## 本地证据 - 研究对象：`ShouZhengAI/CS146S_CN` - 当前研究角色：中文课程与 assignments -- 本轮成熟度：L1 初步理解 - 原始仓库：`raw/repository/` - 原始来源清单：`raw/sources.yml` - 事实摘要：`domain.yml` +- 深度证据：`deep-dive.md` -## 结构观察 +## 对标拆解 -- 根目录包含 `Assignments/`、`Resource/`、`README.md`、图片资源和 `LICENSE`。 -- README 以课程简介、教学大纲、周次主题组织。 -- Assignments 说明它有作业驱动的学习形态。 +| 项 | 内容 | +|:---|:---| +| 参考对象 | `ShouZhengAI/CS146S_CN` | +| 它解决的核心问题 | 用课程大纲和 assignments 把 AI 软件工程学习变成阶段任务 | +| 核心机制 | 周次大纲、`Assignments/`、`Resource/`、课程主题分层 | +| 真正带来结果的动作 | 让学习者通过作业验证工具、agent、测试和自动化能力 | +| 可迁移做法 | assignments 验证层、阶段学习节奏、测试安全进入进阶路径 | +| 不可迁移条件 | 不复制课程内容，不把课程节奏当生产工程流程 | +| 下一步试用动作 | 为本仓 learning-map 增加最小 assignments 列表 | -## 可借鉴点 +## 改良迭代 -- 课程节奏可以作为本仓学习地图的时间序列参考。 -- AI 测试与安全、现代软件支持、自动化 UI 应被纳入进阶路径。 -- Assignments 可以作为实践验证层，而不是只读文档。 +| 改良目标 | 原模式 | 本仓版本 | 验证指标 | +|:---|:---|:---|:---| +| 阶段学习 | 周次课程大纲 | getting-started 分阶段路线 | 每阶段有任务和验收 | +| 作业验证 | Assignments | 本仓练习任务或 workflow checklist | 用户能提交结果或自检 | +| 进阶主题 | 测试安全、终端、自动化 UI | workflow / references 进阶路径 | 进阶内容不只停留在概念 | -## 风险和边界 +## 可迁移清单 -- 课程内容未必覆盖生产工程治理。 -- 作业质量需要逐个验证。 -- 它是课程对象，不适合承担工具生态判断。 +- 为学习路径增加 assignments，而不是只放阅读链接。 +- 把测试、安全、自动化 UI 纳入进阶路径。 +- 将 prompt、tool calling、RAG、MCP、agent workflow 等主题拆成练习。 +- 每个练习提供目标、输入、输出、验证方式和常见失败。 -## 下一轮研究任务 +## 不可迁移清单 -- 梳理 `Assignments/` 的作业类型，判断能否转成本仓练习。 -- 把教学大纲映射到本仓 getting-started / concepts / workflow。 +- 不复制课程内容或作业答案。 +- 不把课堂节奏等同于项目交付节奏。 +- 不在没有验证路径时扩张练习数量。 + +## 验证动作 + +| 动作 | 成功信号 | 失败信号 | +|:---|:---|:---| +| 抽样设计 3 个 assignments | 每个有目标、交付物、验收 | 只是阅读题 | +| 将一个进阶主题转成练习 | 用户能执行并检查结果 | 仍只是概念介绍 | +| 给练习补常见失败 | 卡住时有排查路径 | 失败只能回到问 AI | ## 沉淀判断 -- 本轮只完成 L1 理解，不直接迁入 concepts、references、workflow 或 skills。 -- 只有经过 L2 源码阅读、实验验证或交叉对照后的结论，才进入稳定层。 \ No newline at end of file +- 稳定结论进入 `docs/getting-started/` 和 `docs/workflow/`。 +- 本研究域保持 P2 课程 assignments 对标对象。 diff --git a/docs/research/tradecatlabs-vibe-coding-cn/analysis.md b/docs/research/tradecatlabs-vibe-coding-cn/analysis.md index af68e8b..bc812da 100644 --- a/docs/research/tradecatlabs-vibe-coding-cn/analysis.md +++ b/docs/research/tradecatlabs-vibe-coding-cn/analysis.md @@ -2,43 +2,65 @@ ## 本轮结论 -- 这是本仓自身的外部视角研究域，用来把自身作为基准对象审视。 -- 它的核心资产是 docs、prompts、skills、assets、tools、metadata、AGENTS 和质量门禁，而不是单个应用。 -- 作为研究对象时，重点不是自夸，而是持续发现自身结构债、索引漂移和可沉淀方法。 +`tradecatlabs/vibe-coding-cn` 作为自研究域，价值不是自我表扬，而是用外部成熟样本反向校准自身。 +本仓已经具备 docs、prompts、skills、assets、tools、metadata、scripts、AGENTS、llms 和质量门禁， +但真正的下一步是把这些入口变成“AI 原生知识库控制面”。 + +本仓最应该迁移的是自我审计机制：每次外部研究都必须反问本仓哪里该改、哪里不能膨胀、如何验证改动有效。 ## 本地证据 - 研究对象：`tradecatlabs/vibe-coding-cn` - 当前研究角色：中文主线工程化工作流 -- 本轮成熟度：L1 初步理解 - 原始仓库：`raw/repository/` - 原始来源清单：`raw/sources.yml` - 事实摘要：`domain.yml` +- 深度证据：`deep-dive.md` -## 结构观察 +## 对标拆解 -- 根目录包含 `docs/`、`prompts/`、`skills/`、`assets/`、`tools/`、`metadata/`、`scripts/`、`Makefile`、`AGENTS.md`。 -- README 包含核心命题、字多不看、AI 推荐摘要、入口关系、资源入口和项目结构。 -- 项目已经有本地质量门禁、AI citation、external resources、research domains 等治理层。 +| 项 | 内容 | +|:---|:---| +| 参考对象 | `tradecatlabs/vibe-coding-cn` | +| 它解决的核心问题 | 用中文知识库、提示词、技能、资源和门禁组织 Vibe Coding 学习与实践 | +| 核心机制 | `docs/`、`prompts/`、`skills/`、`assets/`、`metadata/`、`scripts/`、`AGENTS.md`、`llms.txt` | +| 真正带来结果的动作 | 把文档知识库工程化，让 AI 和人类都能稳定读取、验证和交付 | +| 可迁移做法 | 自我研究、索引门禁、AI 引用入口、raw 事实层、资源治理 | +| 不可迁移条件 | 不因外部平台化项目而过早变成应用仓库或工具平台 | +| 下一步试用动作 | 用研究迁移综合驱动 scripts、resources、workflow、skills 的下沉任务 | -## 可借鉴点 +## 改良迭代 -- 自研究域可以作为架构复盘入口，防止项目只向外研究、不审视自身。 -- docs/prompts/skills/assets/tools/metadata 的分层适合作为中文 Vibe Coding 知识库基线。 -- 质量门禁和目录契约是 AI 协作可靠性的基础。 +| 改良目标 | 原模式 | 本仓版本 | 验证指标 | +|:---|:---|:---|:---| +| 自我审计 | 外部研究后停留在 research | 每个研究结论映射到本仓改动或不采用理由 | 研究能产生下游任务 | +| 控制面 | docs/prompts/skills/assets/scripts 分散 | AI 原生知识库控制面 | 入口、owner、验证命令清楚 | +| 防膨胀 | 看到外部结构就想复制 | 只迁移机制，不复制外壳 | 新增对象有存在性证明 | -## 风险和边界 +## 可迁移清单 -- 自我研究容易自我确认，重要结论必须和其他仓库交叉对照。 -- 文档增长过快会带来索引负担。 -- 资源、研究、概念、参考之间的边界需要持续治理。 +- 将 Codex 的执行控制面迁移到 scripts 治理。 +- 将 Aider 的 Git 闭环迁移到 workflow。 +- 将 Cline 的多入口契约迁移到 README/AGENTS/llms/metadata。 +- 将 awesome-claude-code 的资源治理迁移到 assets。 +- 将 Claude Code Best Practice 的方法论资产化迁移到 concepts/workflow/skills。 -## 下一轮研究任务 +## 不可迁移清单 -- 把本仓与 Codex、Cline、Aider、Claude Code Best Practice 做横向差距分析。 -- 定期从自身 Git diff 和门禁失败中提炼治理 lesson。 +- 不把本仓变成 Codex/Cline 类产品。 +- 不把每个外部仓库结构都复制到本仓。 +- 不让 research 无限变厚；成熟结论必须下沉。 +- 不用自研究替代外部交叉审计。 + +## 验证动作 + +| 动作 | 成功信号 | 失败信号 | +|:---|:---|:---| +| 为 P1 研究结论建立下游任务 | 每条结论有目标位置和验收 | 研究停在总结 | +| 检查新增入口的同步链 | README、metadata、llms、AGENTS 同步 | 新入口只有一个文件知道 | +| 抽样一次自我审计 | 能指出应该删减或不做什么 | 只会增加新目录 | ## 沉淀判断 -- 本轮只完成 L1 理解，不直接迁入 concepts、references、workflow 或 skills。 -- 只有经过 L2 源码阅读、实验验证或交叉对照后的结论，才进入稳定层。 \ No newline at end of file +- 稳定结论进入 `docs/research/research-transfer-synthesis.md`、`docs/workflow/`、`scripts/` 和 `assets/`。 +- 本研究域保持 P1 自我校准对象。 diff --git a/docs/research/wendy7756-vibe-coding-guide/analysis.md b/docs/research/wendy7756-vibe-coding-guide/analysis.md index 57477b8..60f6d87 100644 --- a/docs/research/wendy7756-vibe-coding-guide/analysis.md +++ b/docs/research/wendy7756-vibe-coding-guide/analysis.md @@ -2,43 +2,61 @@ ## 本轮结论 -- 这是面向非程序员的自然语言编程指南，价值在低门槛表达、工具解释和工作流概念化。 -- 它把 IDEs and Tools、LLMs、Prompts、my-experience 分目录组织，适合观察非工程读者需要什么上下文。 -- 本仓应吸收其“自然语言描述 -> AI 生成 -> 执行观察”的解释框架，但工程交付标准仍需更严格。 +`wendy7756/vibe-coding-guide` 的核心价值是非程序员视角。它把 IDE、LLM、Prompt 和个人经验分目录组织， +说明新手真正卡住的不是某个工具，而是语言、模型、工具和执行环境之间的关系。 + +本仓应该迁移它的“自然语言描述 -> AI 生成 -> 执行观察”解释框架，但必须补上 Git、测试、回滚和质量门禁。 ## 本地证据 - 研究对象：`wendy7756/vibe-coding-guide` - 当前研究角色：非程序员自然语言编程指南 -- 本轮成熟度：L1 初步理解 - 原始仓库：`raw/repository/` - 原始来源清单：`raw/sources.yml` - 事实摘要：`domain.yml` -## 结构观察 +## 对标拆解 -- 根目录包含 `IDEs-and-Tools/`、`LLMs/`、`Prompts/`、`my-experience/`、`README.md`、`README_EN.md`。 -- README 包含什么是 Vibe Coding、核心定义、起源发展、技术基础、核心工作流程。 -- 目录面向学习者，不是工具源码。 +| 项 | 内容 | +|:---|:---| +| 参考对象 | `wendy7756/vibe-coding-guide` | +| 它解决的核心问题 | 让非程序员理解 Vibe Coding 的语言、工具、模型和提示词关系 | +| 核心机制 | `IDEs-and-Tools/`、`LLMs/`、`Prompts/`、`my-experience/` 分层 | +| 真正带来结果的动作 | 先解释对象关系，再进入工具操作 | +| 可迁移做法 | 非程序员路径、术语解释、经验型障碍清单 | +| 不可迁移条件 | 不弱化测试、版本控制、质量门禁和交付标准 | +| 下一步试用动作 | 为 getting-started 增加“非程序员先理解什么”的入口段 | -## 可借鉴点 +## 改良迭代 -- 非程序员入口要先解释语言、工具、模型和提示词之间的关系。 -- 经验目录能补足正式教程缺少的真实使用感。 -- 中英文 README 可以作为术语表达对照。 +| 改良目标 | 原模式 | 本仓版本 | 验证指标 | +|:---|:---|:---|:---| +| 低门槛入口 | IDE / LLM / Prompt 分层解释 | 对象、目标、上下文、约束、验证五件事先讲清 | 非程序员能描述任务输入输出 | +| 经验障碍 | my-experience 承载个人经验 | 本仓沉淀常见误区和修正动作 | 常见问题能链接到对应文档 | +| 工程补强 | 概念解释为主 | 加入 Git、测试、回滚和门禁 | 新手不会只依赖聊天窗口 | -## 风险和边界 +## 可迁移清单 -- 概念解释多，工程验证少。 -- 非程序员视角可能弱化测试、版本控制和回滚。 -- 需要避免把经验性表述上升为工程原则。 +- 把非程序员最先需要理解的对象关系写清：人、AI、提示词、工具、代码、运行环境。 +- 用经验障碍反推 getting-started 的说明顺序。 +- 提供“预期 vs 实际 + 最小复现”的 debug 表达模板。 +- 将 prompt 模式候选进入提示词库前做质量筛选。 -## 下一轮研究任务 +## 不可迁移清单 -- 抽取非程序员路径中的关键障碍，反馈到本仓 getting-started。 -- 对照其 Prompts 目录，筛选可进入 prompts 表格的提示词模式。 +- 不把个人经验当成硬规则。 +- 不降低工程交付标准来迁就低门槛。 +- 不把 prompt 技巧当作 Vibe Coding 全部。 + +## 验证动作 + +| 动作 | 成功信号 | 失败信号 | +|:---|:---|:---| +| 写一段非程序员入口说明 | 读者能说清 AI 需要什么上下文 | 仍然只知道“让 AI 写代码” | +| 抽取 5 个常见障碍 | 每个障碍有修正动作 | 障碍只是情绪描述 | +| 筛选 prompt 模式 | 能进入提示词表或被明确淘汰 | prompt 无质量边界 | ## 沉淀判断 -- 本轮只完成 L1 理解，不直接迁入 concepts、references、workflow 或 skills。 -- 只有经过 L2 源码阅读、实验验证或交叉对照后的结论，才进入稳定层。 \ No newline at end of file +- 稳定结论进入 `docs/getting-started/` 和提示词库治理。 +- 本研究域保持 P3 非程序员视角观察对象。 diff --git a/llms.txt b/llms.txt index 0c8e0fd..a18bb48 100644 --- a/llms.txt +++ b/llms.txt @@ -53,6 +53,7 @@ vibe-coding-cn 是一个中文 Vibe Coding / AI 结对编程系统教程，帮 - docs/research/README.md - docs/research/research-domain-contract.md - docs/research/research-value-application-map.md +- docs/research/research-transfer-synthesis.md - docs/research/harness/harness-engineering.md - docs/research/openai-codex/README.md - docs/research/shanraisshan-claude-code-best-practice/README.md diff --git a/metadata/taxonomy.yml b/metadata/taxonomy.yml index 96dcb9b..facbe7b 100644 --- a/metadata/taxonomy.yml +++ b/metadata/taxonomy.yml @@ -172,6 +172,9 @@ documents: - path: docs/research/research-value-application-map.md title: 研究价值与应用地图 role: 研究体系给用户带来的价值、核心启示、应用位置和下沉路线 + - path: docs/research/research-transfer-synthesis.md + title: 研究迁移综合 + role: 将对标拆解、改良迭代和杂交创新转成可执行研究路线 - path: docs/research/harness/harness-engineering.md title: Harness 工程解析 role: 工程控制、评估器、反馈闭环与 AI 生成系统可靠性