kc-beta 0.3.2 → 0.5.4

package/template/skills/zh/meta-meta/task-decomposition/SKILL.md

@@ -168,6 +168,22 @@ description: Decompose each verification rule into independent sub-tasks and ass
 | `template` | 模板填充（批注生成等） |
 | `manual_review` | 人工审核 |
 
+## 多智能体协同 —— 不要用锁
+
+如果一个任务大到你打算用 `agent_tool` 起多个子智能体并行做，按独立单元分片（一个规则一个子智能体、一份文档一个子智能体），让子智能体之间不需要通过共享可变文件来协同。
+
+来自一个友邻团队的失败教训：他们让所有子智能体平等，通过共享协同文件领任务，并加锁防抢占。两类失败必然出现：
+
+1. 锁被持有太久，或者干脆忘了释放。即便锁机制工作，二十个智能体的吞吐会下降到只有两三个的水平 —— 大部分时间都在等。
+2. 系统脆弱：智能体可能在持有锁时崩溃，或重复获取自己已经持有的锁，或干脆不获取锁就更新协同文件。
+
+KC 偏好的两种模式：
+
+- **单调度器** —— `TaskManager` 一次发一个任务给主 conductor。无锁，无 peer 协同。这是 ralph-loop 的默认架构。
+- **按单元分片** —— 用 `agent_tool` 起子智能体时，每个子智能体只负责一个不重叠的切片（一规则、一文档）。子智能体的状态写到自己的 `sub_agents/<taskId>/` 下，共享产物（`rule_skills/<id>/`、`workflows/<id>/`）按规则路径分开。Block 11 的 git 自动提交把共享路径的写入序列化，按规则分片让"后写覆盖前写"不再是问题。
+
+如果两个本应并行的子智能体非要相互通信才能推进，那它们其实应该是一个任务（顺序跑）或一条流水线（父智能体发完 A 再发 B），而不是平行的 peer。
+
 ## 反模式
 
 ### LLM 万能论

package/template/skills/zh/meta-meta/version-control/SKILL.md

@@ -5,6 +5,19 @@ description: Manage versioning of skills, workflows, prompts, and system configu
 
 # 版本控制与制品溯源
 
+## Git 即唯一真相源
+
+工作区是一个 git 仓库。每次对受跟踪路径（skills、workflows、rules、glossary、AGENT.md、tasks.json）的写入，都由 KC 自动提交，提交信息中带有 trace ID。这意味着：
+
+- `git log --oneline` 就是本次 session 中所有有意义变更的时间线。
+- `git diff HEAD~3 -- rule_skills/R001/` 显示某个技能在最近三次有意义写入间的变化。
+- `git checkout HEAD~5 -- workflows/R001/` 回滚一个工作流，不影响其他任何东西。
+- `snapshot` 工具用来标记值得记住的时刻（发版、"高风险操作前"），用 `git checkout snap/<label>` 恢复。
+
+通过 `sandbox_exec` 加 `cwd: "workspace"` 直接跑 git 命令。不要绕开 git —— 它就是审计链路本身。
+
+下文中按版本号复制文件名（`workflow_v1.py`、`workflow_v3.py`）和 CHANGELOG.md 的约定依然有用，但作用是 *在单个技能文件夹内提升人类可读性* —— 让智能体直接对比，不必每次都去翻 git 历史。系统的真相记录在 git，不在已废弃的 `versions.json` manifest（新工作区不再写入这个文件）。
+
 ## 设计目标
 
 这套版本控制机制不是为了多人协作——在这个系统中，编程智能体是唯一的执行者。版本控制的目的是：

package/template/workspace.gitignore

@@ -0,0 +1,22 @@
+# Auto-installed by KC at session start. Do not commit secrets, runtime
+# noise, or user source documents — git tracks KC's outputs only.
+
+# Secrets
+.env
+
+# Runtime / session noise
+logs/
+sub_agents/
+session-state.json
+.DS_Store
+*.log
+
+# User-provided source documents (read in place, not tracked)
+samples/
+
+# High-volume IO
+input/
+output/
+
+# Deprecated metadata manifest (old workspaces only — replaced by git)
+versions.json