接手一个开源项目后，我在一个 commit 里做了什么 —— 红旗 Skill 二次开发手记
接手一个成熟的开源项目，最怕两件事：一是看不懂前人的架构，二是改了不该改的地方。这篇文章记录我接手「求是 Skill」后的一次完整二次开发重构——在一个 commit 里完成了品牌更名、方法论扩展和工作流整合，26 个文件，+603/-171 行。
一、缘起：接手求是 Skill
2026 年 3 月 25 日，开发者 HughYau 在 GitHub 上提交了「求是 Skill」（qiushi-skill）的第一个 commit。这不是一个 demo，而是一个从零到完整可用的 Claude Code 插件：35 个文件，2427 行代码，包含 9 个思想武器、一套 hook 注入系统、多平台插件配置和完整文档。
它的核心设计很巧妙——不是传统的"把所有 prompt 塞给 AI"，而是一个技能路由系统。入口 skill arming-thought 像一个轻量路由器，在每次新会话开始时自动注入，然后根据用户任务特征按需调度下游 skill。这种做法避免了 context window 被不相关的内容撑爆。
从教员的方法论体系中，HughYau 提炼出了三层次武器框架：
精神底色（精益求精 · 坚持到底）
↓
总原则（实事求是）
↓
第一层：哲学基座 → 矛盾分析法 · 实践认识论
第二层：工作方法 → 调查研究 · 群众路线 · 批评与自我批评
第三层：战略战术 → 持久战略 · 集中兵力 · 星火燎原 · 统筹兼顾
作为一个 AI Agent 方法论框架，这套体系已经能够覆盖"怎么分析问题 → 怎么收集信息 → 怎么执行决策 → 怎么审视改进"的完整循环。
但有一个问题。
如果你读过《在延安文艺座谈会上的谈话》和《反对党八股》，你会发现教员思想中还有两个不可或缺的维度没有被纳入：“为谁服务”（政治性）和"怎么表达"（文风）。缺少这两者，就好比一套武功有内功心法、有战术拳法，却没有告诉你为谁而战、怎么说话——战斗力会打折扣。
这就是我（KiriAky 107）接手时的起点。
二、评估：接手前的代码审查
接手一个开源项目，第一步永远不是写代码，而是读懂架构。HughYau 的代码组织让人很舒服：
qiushi-skill/
├── .claude-plugin/plugin.json # Claude Code 插件配置
├── .cursor-plugin/plugin.json # Cursor 插件配置
├── .codex/INSTALL.md # Codex 安装入口
├── .opencode/INSTALL.md # OpenCode 安装入口
├── commands/ # 12 个 slash command 入口
├── hooks/ # SessionStart 注入系统
│ ├── hooks.json
│ ├── session-start # POSIX shell 版
│ ├── session-start.ps1 # Windows PowerShell 原生版
│ └── run-hook.cmd # Windows 适配层
├── agents/ # 可派遣的专项 subagent
│ └── self-critic.md
├── skills/ # 9 个思想武器 + 路由入口 + 工作流
├── tests/ # 跨平台验证脚本
└── docs/ # 平台文档 + GitHub Pages 官网
几个关键的架构决策让我印象深刻：
一是核心资产的平台无关性。 所有 skill 都是纯 Markdown 文件，不依赖任何特定平台的 API。.claude-plugin/、.cursor-plugin/ 这些只是适配壳——任何支持 system prompt 注入的 AI 工具都能直接用 skills/ 目录。
二是 hook 注入的跨平台设计。 Windows 上走原生 PowerShell（session-start.ps1），通过 run-hook.cmd 做适配；macOS/Linux 上走 POSIX shell。从 v1.2.0 起彻底不再依赖 Git Bash/WSL。这个设计让安装门槛降到了最低。
三是验证系统的完整性。 tests/validate.sh 和 tests/validate.ps1 覆盖了 JSON 有效性、文件完整性、frontmatter 格式、本地链接存在性——甚至包括 PowerShell hook 的 smoke test。
四是社区参与的健康度。 项目在两周内收到了两个社区 PR：#7（修正安装命令 + macOS/Linux 验证脚本）和 #34（修复 OpenCode 安装链接）。Star History 图表显示项目在持续增长。
评估结论很明确：不需要重写，骨架完好，只需要在正确的位置添砖加瓦。 HughYau 留下的架构扩展性很好——新增 skill 只需在 skills/ 下加目录，在 arming-thought/SKILL.md 的路由表里加一行，在 commands/ 下加一个入口文件。
三、执行：一个 commit 里的完整重构
2026 年 4 月 9 日，我提交了 e6e1aef。这是接手后的第一个也是唯一一个改动——我把所有关联修改压在了一个原子提交里。
为什么是一个 commit？ 因为品牌更名、方法论扩展、工作流整合、文档同步是不可分割的关联变更。如果分成多个 commit，中间任何一个半成品状态都会导致项目不可用——比如改了 plugin.json 里的名字但还没改 hooks 里的命名空间，或者加了新 skill 但还没更新路由表。
以下是这个 commit 的四个维度。
3.1 品牌重构：从「求是」到「红旗」
"求是"和"红旗"的区别不是文字游戏。
“求是”（实事求是）是全部思想武器共同服从的认识论准绳——它是一个内部约束，管的是"你怎么判断对错"。“红旗"则是一个外部指向——它问的是"你举的是什么旗，你为谁服务”。
这个改名不是对 HughYau 工作的否定，而是补充。求是的方法论被完整保留为总原则；在此之上，"红旗"增加了一层方向性的追问。
但改名是最危险的重构。所有引用点必须一次性更新，遗漏任何一处都会造成断裂。以下是完整的修改清单：
| 文件 | 改动 |
|---|---|
.claude-plugin/plugin.json |
qiushi-skill → hongqi-skill |
.cursor-plugin/plugin.json |
同上 |
package.json |
同上 |
.codex/INSTALL.md |
标题和说明中的项目名 |
.opencode/INSTALL.md |
同上 |
hooks/session-start.ps1 |
<QIUSHI_SKILL> → <HONGQI_SKILL>，qiushi:arming-thought → hongqi:arming-thought |
hooks/session-start |
同上 |
skills/arming-thought/SKILL.md |
命名空间更新 + 路由表新增两行 |
README.md |
全文替换项目名、所有链接（GitHub、Star History、介绍页） |
docs/index.html |
官网全面重写 |
docs/README.codex.md |
项目名替换 |
docs/README.opencode.md |
项目名替换 |
tests/validate.sh |
项目名替换 |
tests/validate.ps1 |
项目名替换 |
这里有一个容易被忽视的技术细节：hooks 中的命名空间 <QIUSHI_SKILL> 不只是装饰——它是注入到 AI 会话 context 中的 XML 标签。如果改名时漏掉了这里，AI 在会话中看到的标识和实际 skill 名不一致，会导致调用失败。这种跨文件的"隐式契约"是最容易出 bug 的地方。
3.2 方法论完善：从 9 个到 11 个思想武器
这是本次重构的核心——新增两个思想武器，补全了教员方法论体系的关键缺口。
🎯 政治性（political-commitment）：选自《在延安文艺座谈会上的谈话》（1942 年）。这不是抽象的政治表态，而是一个具体的方法论工具：在输出之前追问"我的立场是什么？我为谁服务？我回避了哪个该直面的矛盾？"。它解决的是 AI Agent 输出中常见的"和稀泥"问题——看似客观中立，实则回避了真正重要的矛盾。
✍️ 文风（writing-style）：选自《反对党八股》（1942 年）。它把"好文风"的定义从模糊的审美标准变成了可操作的检查清单——九条罪状（空话连篇、装腔作势、借以吓人……），每条都有明确的"表现"和"后果"。输出之前逐条自检，就能把"感觉不对"变成"具体哪里不对"。
这两个 skill 被归入现有架构的不同层级：
- 政治性 → 第一层「哲学基座」：它不是某个具体的工作方法，而是和矛盾分析、实践认识论同级别的底层框架——回答的是"往哪走"的根本问题。
- 文风 → 第二层「工作方法」：它是日常输出的质量保障工具，和调查研究、批评与自我批评并列。
每个新 skill 都包含三个组件：
SKILL.md：核心方法论（144 行 / 132 行）original-texts.md：原著引用依据（各 77 行）commands/<name>.md：slash command 入口
同时更新了两个关键位置：
skills/arming-thought/SKILL.md的路由表新增两行触发条件commands/目录新增两个手动命令入口
新增的文件总量约为 450+ 行，全部遵循 HughYau 建立的 skill 文件格式规范：YAML frontmatter → 核心原则 → 不适用场景 → 触发条件 → 方法流程。这种一致性保证了新 skill 可以无缝融入现有的路由调度系统。
3.3 工作流整合：群众路线循环的升级
三条标准化工作流中，Workflow 3「方案迭代优化」是受益最大的。原来的结构是：
mass-line → contradiction-analysis → practice-cognition → criticism-self-criticism → mass-line（循环）
改造后变成了：
mass-line → contradiction-analysis → practice-cognition → political-commitment → writing-style → criticism-self-criticism → mass-line（循环）
新增的 Step 4（政治性检查）和 Step 5（文风检查）被精确地放在 practice-cognition 之后、criticism-self-criticism 之前。这个位置是精心设计的：
- 在实践认识论之后：方案已经经过验证和迭代，内容是确定的，此时检查立场和文风才有意义——你不会对着一个还没成型的东西做文风审查。
- 在批评与自我批评之前：政治性和文风是两个具体的检查维度，它们的结果可以成为 criticism-self-criticism 的输入材料——先做专项检查，再做系统性审视。
每个新步骤都定义了明确的输入、输出格式和终止条件。比如文风检查的终止条件是"通过九条罪状自检"，这个条件是可验证的——要么每一项都打了勾，要么没有。
3.4 配置与文档的全面同步
除了架构层面的改动，配置和文档层面也做了若干重要更新：
README 的重写相对克制。核心改动包括：mermaid 架构图新增政治性和文风两个节点、思想武器表格从 9 行扩展到 11 行（包含原著出处和适用场景）、所有链接从 qiushi-skill 更新为 hongqi-skill。一个值得注意的细节是：将标题区域的图片 Logo 改为纯文本 CSS 样式——更好的可访问性和加载性能。
安装文档简化。HughYau 在重构前一天（4 月 8 日）刚添加了通过 Claude Plugin Hub 安装的方法，这个提交中将其移除，回归到手动安装的单一推荐方式。这不是否定 Plugin Hub 的价值，而是在项目更名初期保持安装路径的清晰——等新名称在各平台稳定后再加回来。
官网全面重写。docs/index.html 经历了 170 行的改动（删除了 HughYau 刚添加的书法图片和头像资产）。在更名的背景下，保持旧品牌视觉元素会造成用户困惑，所以选择了一个更干净的版本。
四、关系：重构者与原作者的协作模式
把这个重构放在完整的时间线上看，两位开发者的协作模式就清晰了：
03-25 HughYau init（35 files, 2427 lines）
03-26 HughYau ×3 commits（Windows 支持、技能文档、工作流）
04-01 Arnold PR #7（修正安装命令 + 验证脚本）
04-02 Renxiang Merge PR #7
04-08 HughYau ×7 commits（Star History、官网、重构、Logo、Plugin Hub）
04-09 Hugh Merge PR #34
04-09 KiriAky 项目重命名 + 两个新武器（26 files, +603/-171）
几个关键观察：
第一，HughYau 在重构前一天还在密集提交。 4 月 8 日这一天他提交了 7 次，包括两次标记为 “Refactor code structure” 的提交——一次重构了官网的 CSS 和 HTML 结构（c7c66a3，+85/-30），一次重命名了 Logo 文件（33ad1d0，logo.png → logo_main.png）。这说明项目在交接时处于高度活跃状态，而不是"做完了放那儿"的存档项目。
第二，重构不是推倒重来，而是继承发展。 仔细看 e6e1aef 的 diff 会发现：skill 文件的格式没有变、hooks 的注入机制没有变、arming-thought 的路由逻辑没有变、工作流的调用规范没有变。改动严格限定在三个方向：品牌名称、新增内容、文档同步。这是对原架构的最大尊重。
第三，社区治理没有断层。 HughYau 在 4 月 9 日上午还合并了社区 PR #34（e2708f9）。同一天晚上我的重构提交上线。项目从个人项目到多人协作的过渡是平滑的——PR 继续合并，issue 继续开放，Star 继续增长。
第四，这种模式值得被更多人借鉴。 开源项目中最常见的两种失败模式：一是"接手就重写"（不尊重前人的设计意图），二是"不敢改"（在糟糕的架构上修修补补）。红旗 Skill 的这次交接走了一条中间道路——足够尊重原架构，又足够大胆地补充它缺失的部分。
五、技术启示：如何干净地接手一个开源项目
回顾这次重构，有几个原则是值得总结的：
先读懂架构，再动手。 我在提交前花了大量时间阅读 HughYau 的 skill 文件格式规范、hooks 注入流程和路由调度逻辑。新增的政治性和文风 skill 完全遵循现有的 SKILL.md 模板（frontmatter 格式、章节结构、触发条件表述方式），这让它们可以直接被 arming-thought 路由系统识别，不需要修改任何调度代码。
原子提交避免半成品状态。 品牌更名、方法扩展、文档同步是强关联变更——只要有一处不更新，整个项目就处于断裂状态。26 个文件的一个 commit 看似"大"，但它保证了项目在任何一个历史版本上都是可用的。拆成多个 commit 反而会制造不可用的中间状态。
改名是最危险的重构之一。 qiushi → hongqi 这个改动分散在 19 个文本文件中，包括 JSON 配置、Markdown 文档、Shell 脚本、PowerShell 脚本、HTML 页面。关键教训：用 grep 扫一遍所有引用，不要靠记忆——一定会漏。
保持向后兼容。 面向用户的接口（skill 调用名、命令入口、文件路径结构）在改名后依然兼容。/contradiction-analysis 还是 /contradiction-analysis，skills/arming-thought/SKILL.md 还是同样的路径。用户不需要改任何调用方式。
六、结语
从「求是」到「红旗」，从 9 大思想武器到 11 大思想武器，这不只是一个开源项目的版本迭代，更是一次干净的二次开发实践。
HughYau 搭的架子好，让我可以专注于方法论层面的增强，而不是在基建上折腾。他的架构决策——Markdown 即 skill、轻量路由、跨平台 hook、验证系统——每一个都在这次重构中得到了验证：当你想扩展功能时，你只需在正确的位置添加内容，而不需要理解整个系统的内部细节。
好的架构让重构变得简单。好的交接让开源项目可以接力。
如果你也准备接手一个开源项目，我的建议是：先花时间读懂前人的设计意图，然后在正确的位置做正确的事，最后用一个完整的 commit 交付。 前人的代码不是你的敌人——它是你站在上面看得更远的肩膀。
🤖 本文基于红旗 Skill 项目的 git 历史编写，所有 commit hash、文件路径和统计数据均来自实际仓库记录。项目地址：github.com/HughYau/hongqi-skill
