完善 skill_manager 的技能维护能力

.opencode/agents/instruction.md

@@ -49,7 +49,11 @@ Skills 树是**动态生长的**——工作流不是预置的，而是从实际
 - 可被未来同类任务复用
 - 非一次性/临时/猜测
 
-**写入位置**：`skills/workflow/<name>/`，包含 SKILL.md（步骤说明）和 scripts/*.py（分析脚本）。
+**写入位置**：`skills/workflow/<name>/`，包含 SKILL.md（步骤说明）、references/*.md（参考材料）和 scripts/*.py（分析脚本）。
+
+**工具动作**：`write_skill / remove_skill` 维护主 SKILL.md；`append_pattern / remove_pattern` 维护 `## Learned Patterns`；`write_reference / remove_reference` 维护 references/*.md；`write_script / remove_script` 维护 scripts/*.py。`write_skill` 可创建或覆盖完整 SKILL.md。
+
+目录入口也通过 `skill_manager` 维护：更新 `skills/workflow/SKILL.md` 时使用 `write_skill(skill_path="workflow", ...)`，更新根入口 `skills/SKILL.md` 时使用 `write_skill(skill_path="__root__", ...)`。
 
 **脚本编写要求——优先用 pipe 串联**：
 

.opencode/skills/SKILL.md

@@ -39,9 +39,12 @@ Skills 树是动态生长的——没有预置的 workflow，所有工作流从
 
 1. **查已有** — 先检查 `skills/workflow/` 下是否有匹配的 workflow skill
 2. **从零拼装** — 无匹配时，Agent 自行组合 `tjwater_cli` 命令 + Python 脚本完成
-3. **沉淀复用** — 任务完成后复盘，如果流程稳定可复用，用 `skill_manager` 保存到 `skills/workflow/<name>/`（含 SKILL.md + scripts/*.py）
+3. **沉淀复用** — 任务完成后复盘，如果流程稳定可复用，用 `skill_manager` 保存到 `skills/workflow/<name>/`（含 SKILL.md、references/*.md、scripts/*.py）
 4. **原子操作** — 简单查询直接调用 `tjwater_cli`，不走 skill
 
+`skill_manager` 可维护主 SKILL.md、`## Learned Patterns`、references/*.md 和 scripts/*.py；完整写入 SKILL.md 时需包含 `name` 和 `description` frontmatter。
+目录入口也通过 `skill_manager` 维护：`skill_path="workflow"` 对应 `skills/workflow/SKILL.md`，`skill_path="__root__"` 对应 `skills/SKILL.md`。
+
 ## Workflow 脚本编写规范
 
 **原则：尽量用 pipe 串联 CLI 调用，减少 tool calling 次数。**

.opencode/skills/runbook.md

@@ -50,9 +50,10 @@ SSE 事件：
 
 - 所有学习类工具必须带 `reason`
 - `memory_manager`：`add / list / replace / remove`
-- `skill_manager`：`list / append_pattern / remove_pattern / write_reference / remove_reference / write_script / remove_script`
+- `skill_manager`：`list / write_skill / remove_skill / append_pattern / remove_pattern / write_reference / remove_reference / write_script / remove_script`
 - `session_search`：只搜索当前用户 + 当前项目作用域
-- `skill_manager` 写入落到：`## Learned Patterns`、`references/*.md`、`scripts/*.py`
+- `skill_manager` 写入落到：`SKILL.md`、`## Learned Patterns`、`references/*.md`、`scripts/*.py`
+- 目录入口同样走 `skill_manager`：`skill_path="workflow"` 维护 `skills/workflow/SKILL.md`，`skill_path="__root__"` 维护 `skills/SKILL.md`
 
 ## 6) 用户上下文注入
 

.opencode/skills/workflow/SKILL.md

@@ -26,4 +26,5 @@ description: 供水管网分析工作流目录，描述可复用的分析流程
 - 每个工作流子目录包含独立的 `SKILL.md`，描述目的、步骤、参数与判定阈值
 - 所有数据获取均通过 `tjwater-cli` 命令族（见 `tjwater-cli` skill）
 - 流程中若涉及仿真，遵循"先查结果后触发"原则
-- 新工作流由 `skill_manager` 在线追加，若子目录不存在则无对应工作流
+- 新工作流由 `skill_manager` 在线写入或更新，若子目录不存在则无对应工作流
+- 新增工作流后，如需更新本目录索引，使用 `skill_manager.write_skill(skill_path="workflow", ...)`

.opencode/tools/skill_manager.ts

@@ -3,17 +3,19 @@ import { tool } from "@opencode-ai/plugin";
 import { SkillStore } from "../../src/skills/store.js";
 import { SessionRuntimeContextStore } from "../../src/sessions/runtimeContextStore.js";
 
-const toolContextStore = new SessionRuntimeContextStore();
+export const createSkillManagerTool = (
-const initializePromise = toolContextStore.initialize();
+  skillStore = new SkillStore(),
-const skillStore = new SkillStore();
+  toolContextStore = new SessionRuntimeContextStore(),
-
+  initializePromise: Promise<unknown> = toolContextStore.initialize(),
-export default tool({
+) => tool({
   description:
-    "维护已验证、可复用、非敏感的 workflow 或方法模式。支持 list、append_pattern、remove_pattern、write_reference、remove_reference、write_script、remove_script。",
+    "维护已验证、可复用、非敏感的 workflow 或方法模式。支持 list、write_skill、remove_skill、append_pattern、remove_pattern、write_reference、remove_reference、write_script、remove_script。",
   args: {
     action: tool.schema
       .enum([
         "list",
+        "write_skill",
+        "remove_skill",
         "append_pattern",
         "remove_pattern",
         "write_reference",
@@ -30,7 +32,7 @@ export default tool({
     skill_path: tool.schema
       .string()
       .describe(
-        "Target skill directory path relative to .opencode/skills.",
+        "Target skill directory path relative to .opencode/skills. Use 'workflow' for the workflow index, or '__root__' for the root skills index.",
       ),
     pattern: tool.schema
       .string()
@@ -47,7 +49,7 @@ export default tool({
     content: tool.schema
       .string()
       .optional()
-      .describe("Asset content used by write_reference or write_script."),
+      .describe("Content used by write_skill, write_reference, or write_script."),
   },
   async execute(args, context) {
     await initializePromise;
@@ -84,7 +86,11 @@ export default tool({
     }
 
     const result =
-      args.action === "append_pattern"
+      args.action === "write_skill"
+        ? await skillStore.writeSkill(args.skill_path, args.content ?? "")
+        : args.action === "remove_skill"
+          ? await skillStore.removeSkill(args.skill_path)
+          : args.action === "append_pattern"
             ? await skillStore.appendPattern(args.skill_path, args.pattern ?? "")
             : args.action === "remove_pattern"
               ? await skillStore.removePattern(args.skill_path, args.target_id ?? "")
@@ -113,3 +119,5 @@ export default tool({
     });
   },
 });
+
+export default createSkillManagerTool();

src/learning/orchestrator.ts

@@ -38,7 +38,13 @@ const reviewResultSchema = z.object({
   skills: z
     .array(
       z.object({
-        action: z.enum(["append_pattern", "remove_pattern", "write_reference"]),
+        action: z.enum([
+          "append_pattern",
+          "remove_pattern",
+          "write_reference",
+          "write_skill",
+          "remove_skill",
+        ]),
         confidence: z.number().min(0).max(1),
         content: z.string().optional(),
         evidence: z.string().default(""),
@@ -409,11 +415,15 @@ export class LearningOrchestrator {
               proposal.skill_path,
               proposal.target_id ?? "",
             )
-          : await this.skillStore.writeReference(
+          : proposal.action === "write_reference"
+            ? await this.skillStore.writeReference(
                 proposal.skill_path,
                 proposal.file_path ?? "",
                 proposal.content ?? "",
-            );
+              )
+            : proposal.action === "write_skill"
+              ? await this.skillStore.writeSkill(proposal.skill_path, proposal.content ?? "")
+              : await this.skillStore.removeSkill(proposal.skill_path);
     await writeLearningAuditLog({
       action: `skill-${proposal.action}`,
       detail: sanitizeAuditDetail(result.detail),
@@ -501,10 +511,11 @@ const buildReviewPrompt = ({
     "- Save only reusable workflows, methods, or pitfalls that will help in future similar tasks.",
     "- Prefer append_pattern for concise reusable lessons.",
     "- Use write_reference only for compact durable supporting notes under references/*.md.",
-    "- Do not edit frontmatter or arbitrary sections.",
+    "- Use write_skill only when the conversation establishes a complete reusable SKILL.md with frontmatter name and description; it creates or overwrites the main SKILL.md.",
+    "- Use remove_skill only when the conversation clearly establishes the whole skill is obsolete or invalid.",
     "",
     "Output JSON schema:",
-    `{"summary":"string","memories":[{"action":"add|replace|remove","scope":"user|workspace","content":"string?","target_id":"string?","confidence":0.0,"evidence":"string"}],"skills":[{"action":"append_pattern|remove_pattern|write_reference","skill_path":"string","pattern":"string?","target_id":"string?","file_path":"references/example.md?","content":"string?","confidence":0.0,"evidence":"string"}]}`,
+    `{"summary":"string","memories":[{"action":"add|replace|remove","scope":"user|workspace","content":"string?","target_id":"string?","confidence":0.0,"evidence":"string"}],"skills":[{"action":"append_pattern|remove_pattern|write_reference|write_skill|remove_skill","skill_path":"string","pattern":"string?","target_id":"string?","file_path":"references/example.md?","content":"string?","confidence":0.0,"evidence":"string"}]}`,
     "",
     "If nothing should be saved, return empty arrays.",
     "",

src/skills/store.ts

@@ -18,6 +18,7 @@ import {
 } from "../utils/persistencePolicy.js";
 
 const LEARNED_PATTERNS_MARKER = "## Learned Patterns";
+const ROOT_SKILL_ALIAS = "__root__";
 const PROJECT_ROOT_DIR = resolve(dirname(fileURLToPath(import.meta.url)), "../..");
 const resolveProjectPath = (path: string) =>
   isAbsolute(path) ? path : resolve(PROJECT_ROOT_DIR, path);
@@ -45,7 +46,8 @@ export class SkillStore {
       return null;
     }
     const target = this.skillFilePath(normalizedSkillPath);
-    const current = (await readTextFile(target)) ?? defaultLearnedSkill(normalizedSkillPath);
+    const current =
+      (await readTextFile(target)) ?? defaultSkillDocument(normalizedSkillPath);
     return {
       references: await this.listReferenceFiles(normalizedSkillPath),
       scripts: await this.listScriptFiles(normalizedSkillPath),
@@ -66,7 +68,8 @@ export class SkillStore {
     }
     return this.serializeWrite(async () => {
       const target = this.skillFilePath(normalizedSkillPath);
-      const current = (await readTextFile(target)) ?? defaultLearnedSkill(normalizedSkillPath);
+      const current =
+        (await readTextFile(target)) ?? defaultSkillDocument(normalizedSkillPath);
       const existingPatterns = extractLearnedPatterns(current);
       if (existingPatterns.some((entry) => entry.content === sanitizedPattern)) {
         return { changed: false, detail: "pattern already existed", target };
@@ -90,6 +93,49 @@ export class SkillStore {
     });
   }
 
+  async writeSkill(skillPath: string, content: string) {
+    const normalizedSkillPath = normalizeSkillPath(skillPath);
+    if (!normalizedSkillPath) {
+      return { changed: false, detail: "invalid skill_path", target: "" };
+    }
+    const sanitizedContent = sanitizePersistentDocument(content, 12000);
+    if (!sanitizedContent) {
+      return { changed: false, detail: "skill content rejected by persistence policy", target: "" };
+    }
+    if (!hasValidSkillFrontmatter(sanitizedContent)) {
+      return {
+        changed: false,
+        detail: "skill content rejected: expected SKILL.md frontmatter with name and description",
+        target: "",
+      };
+    }
+    return this.serializeWrite(async () => {
+      const target = this.skillFilePath(normalizedSkillPath);
+      await ensureDirectory(this.skillDirPath(normalizedSkillPath));
+      await atomicWriteFileWithHistory(target, `${sanitizedContent}\n`, {
+        backupDir: this.backupDir,
+        rootDir: this.rootDir,
+      });
+      return { changed: true, detail: "skill written", target };
+    });
+  }
+
+  async removeSkill(skillPath: string) {
+    const normalizedSkillPath = normalizeSkillPath(skillPath);
+    if (!normalizedSkillPath) {
+      return { changed: false, detail: "invalid skill_path", target: "" };
+    }
+    return this.serializeWrite(async () => {
+      const target = this.skillFilePath(normalizedSkillPath);
+      const previous = await readTextFile(target);
+      if (previous === null) {
+        return { changed: false, detail: "skill file not found", target };
+      }
+      await removeFileIfExists(target);
+      return { changed: true, detail: "skill removed", target };
+    });
+  }
+
   async removePattern(skillPath: string, targetId: string) {
     const normalizedSkillPath = normalizeSkillPath(skillPath);
     if (!normalizedSkillPath) {
@@ -205,18 +251,28 @@ export class SkillStore {
 
   private async listReferenceFiles(skillPath: string) {
     const referenceDir = join(this.rootDir, skillPath, "references");
+    if (skillPath === ROOT_SKILL_ALIAS) {
+      return [];
+    }
     const files = await listFiles(referenceDir);
     return files.map((file) => file.slice(referenceDir.length + 1));
   }
 
   private async listScriptFiles(skillPath: string) {
+    if (skillPath === ROOT_SKILL_ALIAS) {
+      return [];
+    }
     const scriptDir = join(this.rootDir, skillPath, "scripts");
     const files = await listFiles(scriptDir);
     return files.map((file) => file.slice(scriptDir.length + 1));
   }
 
   private skillFilePath(skillPath: string) {
-    return join(this.rootDir, skillPath, "SKILL.md");
+    return join(this.skillDirPath(skillPath), "SKILL.md");
+  }
+
+  private skillDirPath(skillPath: string) {
+    return skillPath === ROOT_SKILL_ALIAS ? this.rootDir : join(this.rootDir, skillPath);
   }
 
   private async serializeWrite<T>(task: () => Promise<T>) {
@@ -231,6 +287,9 @@ export class SkillStore {
 
 export const normalizeSkillPath = (rawSkillPath: string) => {
   const normalized = posix.normalize(rawSkillPath.trim().replace(/^\/+|\/+$/g, ""));
+  if (normalized === ROOT_SKILL_ALIAS) {
+    return ROOT_SKILL_ALIAS;
+  }
   if (!normalized || normalized === "." || normalized.startsWith("..")) {
     return null;
   }
@@ -341,6 +400,26 @@ const extractLearnedPatternsSection = (content: string) => {
   return tail.slice(0, nextHeadingMatch?.index ?? tail.length);
 };
 
+const hasValidSkillFrontmatter = (content: string) => {
+  const match = content.match(/^---\n([\s\S]*?)\n---(?:\n|$)/);
+  if (!match) {
+    return false;
+  }
+  const lines = match[1].split("\n").map((line) => line.trim());
+  return (
+    lines.some((line) => /^name:\s*\S+/i.test(line)) &&
+    lines.some((line) => /^description:\s*\S+/i.test(line))
+  );
+};
+
+const defaultRootSkill = () => `---
+name: skills
+description: TJWater Skills root index.
+---
+
+# TJWater Skills
+`;
+
 const defaultLearnedSkill = (skillPath: string) => `---
 name: tjwater-action-${skillPath
   .split("/")
@@ -349,7 +428,7 @@ name: tjwater-action-${skillPath
   .replace(/[^a-z0-9._-]+/gi, "-")
   .replace(/^-+|-+$/g, "")
   .slice(0, 120) || "generated-skill"}
-description: 由 skill_manager 在线追加的高置信度可复用 workflow。
+description: 由 skill_manager 在线维护的高置信度可复用 workflow。
 version: 1.0.0
 ---
 
@@ -357,7 +436,10 @@ version: 1.0.0
 
 ## 简介
 
-记录由 \`skill_manager\` 在线追加的高置信度 workflow 模式。
+记录由 \`skill_manager\` 在线维护的高置信度 workflow 模式。
 
 ## Learned Patterns
 `;
+
+const defaultSkillDocument = (skillPath: string) =>
+  skillPath === ROOT_SKILL_ALIAS ? defaultRootSkill() : defaultLearnedSkill(skillPath);

tests/opencode/skillManagerTool.test.ts

@@ -0,0 +1,142 @@
+import { afterEach, beforeEach, describe, expect, it } from "bun:test";
+import { mkdtemp, readFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { createSkillManagerTool } from "../../.opencode/tools/skill_manager.js";
+import { SessionRuntimeContextStore } from "../../src/sessions/runtimeContextStore.js";
+import { SkillStore } from "../../src/skills/store.js";
+
+describe("skill_manager tool", () => {
+  let tempDir: string;
+  let skillStore: SkillStore;
+  let contextStore: SessionRuntimeContextStore;
+
+  const toolContext = {
+    abort: new AbortController().signal,
+    agent: "test",
+    ask: (() => undefined) as never,
+    directory: "",
+    messageID: "message-1",
+    metadata: () => undefined,
+    sessionID: "session-1",
+    worktree: "",
+  };
+
+  const skillDocument = (body: string) =>
+    [
+      "---",
+      "name: pressure-review",
+      "description: Pressure review workflow.",
+      "---",
+      "",
+      body,
+    ].join("\n");
+
+  beforeEach(async () => {
+    tempDir = await mkdtemp(join(tmpdir(), "tjwater-skill-tool-"));
+    skillStore = new SkillStore(
+      join(tempDir, "skills"),
+      join(tempDir, "backup", "skills"),
+    );
+    contextStore = new SessionRuntimeContextStore(join(tempDir, "contexts"));
+    await contextStore.initialize();
+    await contextStore.write({
+      actorKey: "actor-1",
+      allowLearningWrite: true,
+      clientSessionId: "client-session-1",
+      projectKey: "project-1",
+      sessionId: "session-1",
+      traceId: "trace-1",
+    });
+  });
+
+  afterEach(async () => {
+    await rm(tempDir, { force: true, recursive: true });
+  });
+
+  it("dispatches skill-level write, overwrite, and remove actions", async () => {
+    const tool = createSkillManagerTool(
+      skillStore,
+      contextStore,
+      Promise.resolve(),
+    );
+
+    const writeResult = JSON.parse(
+      await tool.execute(
+        {
+          action: "write_skill",
+          content: skillDocument("# Pressure Review"),
+          reason: "verified reusable workflow",
+          skill_path: "workflow/pressure-review",
+        },
+        toolContext,
+      ) as string,
+    );
+    expect(writeResult.decision).toBe("accepted");
+    await expect(readFile(writeResult.target, "utf8")).resolves.toContain(
+      "# Pressure Review\n",
+    );
+
+    const updateResult = JSON.parse(
+      await tool.execute(
+        {
+          action: "write_skill",
+          content: skillDocument("# Updated Pressure Review"),
+          reason: "verified reusable workflow overwrite",
+          skill_path: "workflow/pressure-review",
+        },
+        toolContext,
+      ) as string,
+    );
+    expect(updateResult.decision).toBe("accepted");
+    await expect(readFile(updateResult.target, "utf8")).resolves.toContain(
+      "# Updated Pressure Review\n",
+    );
+
+    const removeResult = JSON.parse(
+      await tool.execute(
+        {
+          action: "remove_skill",
+          reason: "workflow is obsolete",
+          skill_path: "workflow/pressure-review",
+        },
+        toolContext,
+      ) as string,
+    );
+    expect(removeResult.decision).toBe("accepted");
+    await expect(readFile(removeResult.target, "utf8")).rejects.toThrow();
+  });
+
+  it("writes the root skills index through the reserved alias", async () => {
+    const tool = createSkillManagerTool(
+      skillStore,
+      contextStore,
+      Promise.resolve(),
+    );
+
+    const writeResult = JSON.parse(
+      await tool.execute(
+        {
+          action: "write_skill",
+          content: [
+            "---",
+            "name: skills",
+            "description: TJWater Skills root index.",
+            "---",
+            "",
+            "# TJWater Skills",
+          ].join("\n"),
+          reason: "refresh root skills index",
+          skill_path: "__root__",
+        },
+        toolContext,
+      ) as string,
+    );
+
+    expect(writeResult.decision).toBe("accepted");
+    await expect(readFile(writeResult.target, "utf8")).resolves.toContain(
+      "# TJWater Skills\n",
+    );
+  });
+});

tests/skills/store.test.ts

@@ -13,6 +13,16 @@ describe("SkillStore", () => {
   let backupRoot: string;
   let store: SkillStore;
 
+  const skillDocument = (name: string, body: string) =>
+    [
+      "---",
+      `name: ${name}`,
+      `description: ${name} workflow.`,
+      "---",
+      "",
+      body,
+    ].join("\n");
+
   beforeEach(async () => {
     originalCwd = process.cwd();
     tempDir = await mkdtemp(join(tmpdir(), "tjwater-skills-"));
@@ -64,4 +74,93 @@ describe("SkillStore", () => {
       target: "",
     });
   });
+
+  it("writes and overwrites the main skill file", async () => {
+    const skillPath = "workflow/pressure-review";
+    const writeResult = await store.writeSkill(
+      skillPath,
+      skillDocument("pressure-review", "# Pressure Review"),
+    );
+
+    expect(writeResult).toEqual({
+      changed: true,
+      detail: "skill written",
+      target: join(skillsRoot, "workflow", "pressure-review", "SKILL.md"),
+    });
+
+    const overwriteResult = await store.writeSkill(
+      skillPath,
+      skillDocument("pressure-review", "# Updated Pressure Review"),
+    );
+
+    expect(overwriteResult).toEqual({
+      changed: true,
+      detail: "skill written",
+      target: writeResult.target,
+    });
+    await expect(readFile(writeResult.target, "utf8")).resolves.toContain(
+      "# Updated Pressure Review\n",
+    );
+  });
+
+  it("writes the root skills index via the reserved alias", async () => {
+    const result = await store.writeSkill(
+      "__root__",
+      [
+        "---",
+        "name: skills",
+        "description: TJWater Skills root index.",
+        "---",
+        "",
+        "# TJWater Skills",
+      ].join("\n"),
+    );
+
+    expect(result).toEqual({
+      changed: true,
+      detail: "skill written",
+      target: join(skillsRoot, "SKILL.md"),
+    });
+    await expect(readFile(result.target, "utf8")).resolves.toContain(
+      "# TJWater Skills\n",
+    );
+  });
+
+  it("removes the main skill file", async () => {
+    const writeResult = await store.writeSkill(
+      "workflow/remove-me",
+      skillDocument("remove-me", "# Remove Me"),
+    );
+    const removeResult = await store.removeSkill("workflow/remove-me");
+
+    expect(removeResult).toEqual({
+      changed: true,
+      detail: "skill removed",
+      target: writeResult.target,
+    });
+    await expect(readFile(writeResult.target, "utf8")).rejects.toThrow();
+  });
+
+  it("rejects sensitive skill content", async () => {
+    const result = await store.writeSkill(
+      "workflow/unsafe",
+      "access_token=secret-value",
+    );
+
+    expect(result).toEqual({
+      changed: false,
+      detail: "skill content rejected by persistence policy",
+      target: "",
+    });
+  });
+
+  it("rejects skill content without required frontmatter", async () => {
+    const result = await store.writeSkill("workflow/incomplete", "# Incomplete");
+
+    expect(result).toEqual({
+      changed: false,
+      detail: "skill content rejected: expected SKILL.md frontmatter with name and description",
+      target: "",
+    });
+  });
 });