OrgTJWater/TJWaterAgent
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

完善 skill_manager 的技能维护能力

Browse Source
This commit is contained in:
Huarch
2026-06-05 13:03:39 +08:00
parent fc0e76439d
commit ad31956f53
9 changed files with 392 additions and 41 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.opencode/agents/instruction.md
+5 -1
View File
@@ -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
+4 -1
View File
@@ -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
+3 -2
View File
@@ -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
+2 -1
View File
@@ -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
+31 -23
View File
@@ -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();
const initializePromise = toolContextStore.initialize();
const skillStore = new SkillStore();
export default tool({
export const createSkillManagerTool = (
skillStore = new SkillStore(),
toolContextStore = new SessionRuntimeContextStore(),
initializePromise: Promise<unknown> = toolContextStore.initialize(),
) => 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,25 +86,29 @@ export default tool({
}
const result =
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 ?? "")
: args.action === "write_reference"
? await skillStore.writeReference(
args.skill_path,
args.file_path ?? "",
args.content ?? "",
)
: args.action === "remove_reference"
? await skillStore.removeReference(args.skill_path, args.file_path ?? "")
: args.action === "write_script"
? await skillStore.writeScript(
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 ?? "")
: args.action === "write_reference"
? await skillStore.writeReference(
args.skill_path,
args.file_path ?? "",
args.content ?? "",
)
: await skillStore.removeScript(args.skill_path, args.file_path ?? "");
: args.action === "remove_reference"
? await skillStore.removeReference(args.skill_path, args.file_path ?? "")
: args.action === "write_script"
? await skillStore.writeScript(
args.skill_path,
args.file_path ?? "",
args.content ?? "",
)
: await skillStore.removeScript(args.skill_path, args.file_path ?? "");
return JSON.stringify({
ok: true,
@@ -113,3 +119,5 @@ export default tool({
});
},
});
export default createSkillManagerTool();
src/learning/orchestrator.ts
+19 -8
View File
@@ -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.skill_path,
proposal.file_path ?? "",
proposal.content ?? "",
);
: 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
+87 -5
View File
@@ -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
+142
View File
@@ -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
+99
View File
@@ -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: "",
});
});
});