chatccc 0.2.227 → 0.2.228

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (6) hide show
  1. package/package.json +1 -1
  2. package/src/__tests__/builtin-skills.test.ts +252 -252
  3. package/src/__tests__/builtin-web-tools.test.ts +220 -0
  4. package/src/builtin/file-tools.ts +37 -0
  5. package/src/builtin/skills.ts +190 -190
  6. package/src/builtin/web-tools.ts +313 -0
package/src/__tests__/builtin-web-tools.test.ts ADDED
@@ -0,0 +1,220 @@
1
+ import { describe, expect, it } from "vitest";
2
+
3
+ import {
4
+ decodeDdgHref,
5
+ extractHtmlTitle,
6
+ htmlToPlainText,
7
+ parseDuckDuckGoHtml,
8
+ webFetchForTool,
9
+ webSearchForTool,
10
+ type FetchLike,
11
+ } from "../builtin/web-tools.ts";
12
+
13
+ const DDG_HTML = `<!DOCTYPE html>
14
+ <html>
15
+ <head><title>Search results</title></head>
16
+ <body>
17
+ <div class="result results_links results_links_deep web-result">
18
+ <h2 class="result__title">
19
+ <a rel="nofollow" class="result__a" href="//duckduckgo.com/l/?uddg=https%3A%2F%2Fnodejs.org%2Fen%2Fdocs&rut=abc">Node.js <b>Docs</b></a>
20
+ </h2>
21
+ <a rel="nofollow" class="result__snippet" href="//duckduckgo.com/l/?uddg=...">Official documentation for Node.js &amp; npm.</a>
22
+ </div>
23
+ <div class="result">
24
+ <a rel="nofollow" class="result__a" href="https://example.com/page">Example &quot;quoted&quot; page</a>
25
+ <a rel="nofollow" class="result__snippet" href="https://example.com/page">A plain snippet without highlight.</a>
26
+ </div>
27
+ </body>
28
+ </html>`;
29
+
30
+ const WEB_FETCH_HTML = `<!DOCTYPE html>
31
+ <html><head><title>Fetch &amp; Me</title></head>
32
+ <body>
33
+ <style>.x { color: red }</style>
34
+ <script>alert("x")</script>
35
+ <h1>Hello World</h1>
36
+ <p>First paragraph with &amp; entity.</p>
37
+ <p>Second paragraph<br>with a break.</p>
38
+ <footer>bye</footer>
39
+ </body></html>`;
40
+
41
+ describe("parseDuckDuckGoHtml", () => {
42
+ it("extracts title, decoded url, and snippet per result", () => {
43
+ const results = parseDuckDuckGoHtml(DDG_HTML);
44
+ expect(results).toHaveLength(2);
45
+ expect(results[0]).toEqual({
46
+ title: "Node.js Docs",
47
+ url: "https://nodejs.org/en/docs",
48
+ snippet: "Official documentation for Node.js & npm.",
49
+ });
50
+ expect(results[1]).toEqual({
51
+ title: 'Example "quoted" page',
52
+ url: "https://example.com/page",
53
+ snippet: "A plain snippet without highlight.",
54
+ });
55
+ });
56
+
57
+ it("returns empty array for pages without results", () => {
58
+ expect(parseDuckDuckGoHtml("<html><body>no results here</body></html>")).toEqual([]);
59
+ });
60
+ });
61
+
62
+ describe("decodeDdgHref", () => {
63
+ it("decodes uddg redirect params and restores protocol", () => {
64
+ expect(
65
+ decodeDdgHref("//duckduckgo.com/l/?uddg=https%3A%2F%2Fnodejs.org%2Fen%2Fdocs&rut=abc"),
66
+ ).toBe("https://nodejs.org/en/docs");
67
+ });
68
+
69
+ it("passes through plain urls", () => {
70
+ expect(decodeDdgHref("https://example.com/a?b=1")).toBe("https://example.com/a?b=1");
71
+ });
72
+
73
+ it("returns input untouched when unparseable", () => {
74
+ expect(decodeDdgHref("not a url")).toBe("not a url");
75
+ });
76
+ });
77
+
78
+ describe("htmlToPlainText", () => {
79
+ it("strips scripts/styles, keeps block boundaries, decodes entities, compresses whitespace", () => {
80
+ const text = htmlToPlainText(WEB_FETCH_HTML);
81
+ expect(text).not.toContain("alert");
82
+ expect(text).not.toContain(".x {");
83
+ expect(text).toContain("Hello World");
84
+ expect(text).toContain("First paragraph with & entity.");
85
+ expect(text).toContain("Second paragraph\nwith a break.");
86
+ expect(text).toContain("bye");
87
+ // 段落间允许单个空行，但不得出现连续空行
88
+ expect(text).not.toContain("\n\n\n");
89
+ });
90
+ });
91
+
92
+ describe("extractHtmlTitle", () => {
93
+ it("extracts and decodes the title", () => {
94
+ expect(extractHtmlTitle(WEB_FETCH_HTML)).toBe("Fetch & Me");
95
+ });
96
+
97
+ it("returns empty string when no title", () => {
98
+ expect(extractHtmlTitle("<html><body>x</body></html>")).toBe("");
99
+ });
100
+ });
101
+
102
+ describe("webSearchForTool", () => {
103
+ function mockFetch(html: string, status = 200): FetchLike {
104
+ return async () =>
105
+ new Response(html, {
106
+ status,
107
+ headers: { "content-type": "text/html; charset=utf-8" },
108
+ });
109
+ }
110
+
111
+ it("returns parsed results from the search page", async () => {
112
+ const output = await webSearchForTool(
113
+ { query: "nodejs docs" },
114
+ { fetchImpl: mockFetch(DDG_HTML) },
115
+ );
116
+ expect(output.query).toBe("nodejs docs");
117
+ expect(output.results).toHaveLength(2);
118
+ expect(output.results[0].url).toBe("https://nodejs.org/en/docs");
119
+ expect(output.results[0].snippet).toContain("Node.js");
120
+ expect(typeof output.durationMs).toBe("number");
121
+ });
122
+
123
+ it("respects maxResults and caps at 10", async () => {
124
+ const html = Array.from({ length: 12 }, (_, i) => {
125
+ const title = `<a rel="nofollow" class="result__a" href="https://e.com/${i}">R${i}</a>`;
126
+ const snippet = `<a rel="nofollow" class="result__snippet" href="https://e.com/${i}">s${i}</a>`;
127
+ return `<div>${title}${snippet}</div>`;
128
+ }).join("");
129
+ const output = await webSearchForTool({ query: "many" }, { fetchImpl: mockFetch(html) });
130
+ expect(output.results).toHaveLength(5);
131
+ expect(output.truncated).toBe(true);
132
+
133
+ const output2 = await webSearchForTool({ query: "many", maxResults: 20 }, { fetchImpl: mockFetch(html) });
134
+ expect(output2.results).toHaveLength(10);
135
+ });
136
+
137
+ it("returns empty results (not an error) when the page has no matches", async () => {
138
+ const output = await webSearchForTool(
139
+ { query: "zzz-nothing" },
140
+ { fetchImpl: mockFetch("<html><body>no results</body></html>") },
141
+ );
142
+ expect(output.results).toEqual([]);
143
+ expect(output.truncated).toBe(false);
144
+ });
145
+
146
+ it("throws on empty query", async () => {
147
+ await expect(webSearchForTool({ query: " " }, { fetchImpl: mockFetch("") })).rejects.toThrow(
148
+ "query is required",
149
+ );
150
+ });
151
+
152
+ it("throws on non-2xx response", async () => {
153
+ await expect(
154
+ webSearchForTool({ query: "x" }, { fetchImpl: mockFetch("blocked", 429) }),
155
+ ).rejects.toThrow("HTTP 429");
156
+ });
157
+ });
158
+
159
+ describe("webFetchForTool", () => {
160
+ function mockFetch(html: string, status = 200, contentType = "text/html; charset=utf-8"): FetchLike {
161
+ return async () =>
162
+ new Response(html, {
163
+ status,
164
+ headers: { "content-type": contentType },
165
+ });
166
+ }
167
+
168
+ it("fetches and converts html to plain text with title", async () => {
169
+ const output = await webFetchForTool(
170
+ { url: "https://example.com/page" },
171
+ { fetchImpl: mockFetch(WEB_FETCH_HTML) },
172
+ );
173
+ expect(output.title).toBe("Fetch & Me");
174
+ expect(output.text).toContain("Hello World");
175
+ expect(output.text).toContain("Second paragraph\nwith a break.");
176
+ expect(output.text).not.toContain("alert");
177
+ expect(output.contentType).toContain("text/html");
178
+ expect(output.chars).toBe(output.text.length);
179
+ expect(output.truncated).toBe(false);
180
+ });
181
+
182
+ it("truncates text beyond maxChars", async () => {
183
+ const output = await webFetchForTool(
184
+ { url: "https://example.com/long", maxChars: 10 },
185
+ { fetchImpl: mockFetch("<p>hello world and more</p>") },
186
+ );
187
+ expect(output.text).toBe("hello worl");
188
+ expect(output.truncated).toBe(true);
189
+ expect(output.chars).toBe(10);
190
+ });
191
+
192
+ it("truncates oversized response bodies", async () => {
193
+ const big = `<!DOCTYPE html><html><body><p>${"a".repeat(600 * 1024)}</p></body></html>`;
194
+ const output = await webFetchForTool(
195
+ { url: "https://example.com/big" },
196
+ { fetchImpl: mockFetch(big) },
197
+ );
198
+ expect(output.truncated).toBe(true);
199
+ expect(output.text.length).toBeLessThan(600 * 1024);
200
+ });
201
+
202
+ it("rejects non-http(s) protocols", async () => {
203
+ await expect(
204
+ webFetchForTool({ url: "file:///etc/passwd" }, { fetchImpl: mockFetch("") }),
205
+ ).rejects.toThrow("unsupported protocol");
206
+ });
207
+
208
+ it("rejects invalid urls", async () => {
209
+ await expect(
210
+ webFetchForTool({ url: "not a url" }, { fetchImpl: mockFetch("") }),
211
+ ).rejects.toThrow("invalid URL");
212
+ });
213
+
214
+ it("throws on missing url and non-2xx", async () => {
215
+ await expect(webFetchForTool({ url: " " })).rejects.toThrow("url is required");
216
+ await expect(
217
+ webFetchForTool({ url: "https://example.com/404" }, { fetchImpl: mockFetch("nf", 404) }),
218
+ ).rejects.toThrow("HTTP 404");
219
+ });
220
+ });
package/src/builtin/file-tools.ts CHANGED
@@ -10,6 +10,14 @@ import { jsonSchema, tool, type ToolSet } from "ai";
10
10
 
11
11
  import { isDangerousCommand, type PermissionGate, type PermissionRequest } from "./permissions.js";
12
12
  import { killProcessTree } from "./proc-tree-kill.js";
13
+ import {
14
+ webFetchForTool,
15
+ webSearchForTool,
16
+ type WebFetchInput,
17
+ type WebFetchOutput,
18
+ type WebSearchInput,
19
+ type WebSearchOutput,
20
+ } from "./web-tools.js";
13
21
 
14
22
  const MAX_READ_BYTES = 1024 * 1024;
15
23
  const MAX_LIST_ENTRIES = 200;
@@ -1403,5 +1411,34 @@ export function createBuiltinFileTools(
1403
1411
  return applyPatchForTool(cwd, input);
1404
1412
  },
1405
1413
  }),
1414
+ // 联网工具：只读外部网络操作，不触碰本地文件系统，无需权限询问
1415
+ websearch: tool<WebSearchInput, WebSearchOutput>({
1416
+ description:
1417
+ "Search the web (DuckDuckGo, no API key) and return matching titles, URLs, and snippets. Use when you need current or external information not available locally, e.g. latest docs, news, or package versions.",
1418
+ inputSchema: jsonSchema<WebSearchInput>({
1419
+ type: "object",
1420
+ additionalProperties: false,
1421
+ properties: {
1422
+ query: { type: "string", description: "Search query." },
1423
+ maxResults: { type: "number", description: "Optional result count, default 5, capped at 10." },
1424
+ },
1425
+ required: ["query"],
1426
+ }),
1427
+ execute: (input, options) => webSearchForTool(input, { abortSignal: options.abortSignal }),
1428
+ }),
1429
+ webfetch: tool<WebFetchInput, WebFetchOutput>({
1430
+ description:
1431
+ "Fetch a URL and return its readable text content (HTML stripped, truncated). Use for documentation pages, articles, or API docs. Only http/https URLs are allowed.",
1432
+ inputSchema: jsonSchema<WebFetchInput>({
1433
+ type: "object",
1434
+ additionalProperties: false,
1435
+ properties: {
1436
+ url: { type: "string", description: "http/https URL to fetch." },
1437
+ maxChars: { type: "number", description: "Optional text length cap, default 10000, capped at 100000." },
1438
+ },
1439
+ required: ["url"],
1440
+ }),
1441
+ execute: (input, options) => webFetchForTool(input, { abortSignal: options.abortSignal }),
1442
+ }),
1406
1443
  };
1407
1444
  }
package/src/builtin/skills.ts CHANGED
@@ -1,190 +1,190 @@
1
- /**
2
- * skills.ts — 多来源技能扫描（DeepCCC 统一入口）
3
- *
4
- * 并行扫描 Claude / Codex / Cursor / DeepCCC 四套目录式技能
5
- * （<name>/SKILL.md + YAML frontmatter，三套生态同构）。
6
- *
7
- * 同名优先级（高 → 低）：deepccc > codex > cursor > claude；
8
- * 同来源内：project（项目级）> global（用户级）。
9
- * 目录列表按低 → 高排列，扫描时后者覆盖前者，天然实现优先级。
10
- *
11
- * 热加载：SKILL.md 内容带 mtime 缓存，文件变化时自动重读；
12
- * 目录枚举每次都做（新技能目录立即被发现）。因此"创建技能 →
13
- * 下一次对话自动生效"，无需重启，也无需常驻 watcher。
14
- */
15
-
16
- import { readdirSync } from "node:fs";
17
- import { readFile, stat } from "node:fs/promises";
18
- import { homedir } from "node:os";
19
- import { join } from "node:path";
20
-
21
- export type SkillSource = "deepccc" | "codex" | "cursor" | "claude";
22
- export type SkillScope = "global" | "project";
23
-
24
- export interface BuiltinSkill {
25
- name: string;
26
- description: string;
27
- /** SKILL.md 的绝对路径 */
28
- skillPath: string;
29
- /** 来源（优先级 deepccc > codex > cursor > claude） */
30
- source: SkillSource;
31
- /** global = 用户级；project = 项目级（同来源内 project > global） */
32
- scope: SkillScope;
33
- }
34
-
35
- export interface SkillDirSpec {
36
- dir: string;
37
- source: SkillSource;
38
- scope: SkillScope;
39
- }
40
-
41
- /** 解析 SKILL.md frontmatter（兼容 CRLF），返回 name + description；无 frontmatter 返回 null */
42
- export function parseSkillFrontmatter(
43
- content: string,
44
- ): { name: string; description: string } | null {
45
- const match = /^---\r?\n([\s\S]*?)\r?\n---\s*(?:\r?\n|$)/.exec(content);
46
- if (!match) return null;
47
- const fm = match[1];
48
- const nameMatch = /^name:\s*(.+?)\s*$/m.exec(fm);
49
- if (!nameMatch) return null;
50
- const descMatch = /^description:\s*(.+?)\s*$/m.exec(fm);
51
- return {
52
- name: nameMatch[1].trim(),
53
- description: descMatch?.[1].trim() ?? "",
54
- };
55
- }
56
-
57
- // ---------------------------------------------------------------------------
58
- // mtime 热加载缓存：同一进程内重复扫描命中缓存（stat 校验），文件变化自动重读
59
- // ---------------------------------------------------------------------------
60
-
61
- const skillFileCache = new Map<string, { mtimeMs: number; content: string }>();
62
-
63
- async function readSkillFile(skillPath: string): Promise<string | null> {
64
- let st;
65
- try {
66
- st = await stat(skillPath);
67
- } catch {
68
- return null;
69
- }
70
- if (!st.isFile()) return null;
71
- const cached = skillFileCache.get(skillPath);
72
- if (cached && cached.mtimeMs === st.mtimeMs) return cached.content;
73
- const content = await readFile(skillPath, "utf8");
74
- skillFileCache.set(skillPath, { mtimeMs: st.mtimeMs, content });
75
- return content;
76
- }
77
-
78
- /**
79
- * 扫描多个 skill 目录（并行读取），按 name 去重。
80
- * 同名技能：后面的 spec（高优先级）覆盖前面的（低优先级）。
81
- * 隐藏目录（.system 等）和无 SKILL.md 的目录会被跳过；缺失目录跳过。
82
- */
83
- export async function scanSkillsDirs(dirs: SkillDirSpec[]): Promise<BuiltinSkill[]> {
84
- const byName = new Map<string, BuiltinSkill>();
85
-
86
- for (const spec of dirs) {
87
- let entries;
88
- try {
89
- entries = readdirSync(spec.dir, { withFileTypes: true });
90
- } catch {
91
- continue; // 目录不存在或不可读：跳过
92
- }
93
-
94
- // 目录内所有候选 SKILL.md 并行读取（读文件是扫描的瓶颈）
95
- const results = await Promise.all(
96
- entries
97
- .filter((entry) => entry.isDirectory() && !entry.name.startsWith("."))
98
- .map(async (entry) => {
99
- const skillPath = join(spec.dir, entry.name, "SKILL.md");
100
- const content = await readSkillFile(skillPath);
101
- if (content === null) return null;
102
- const parsed = parseSkillFrontmatter(content);
103
- if (!parsed) return null;
104
- return { ...parsed, skillPath };
105
- }),
106
- );
107
-
108
- for (const result of results) {
109
- if (!result) continue;
110
- byName.set(result.name, {
111
- name: result.name,
112
- description: result.description,
113
- skillPath: result.skillPath,
114
- source: spec.source,
115
- scope: spec.scope,
116
- });
117
- }
118
- }
119
-
120
- return [...byName.values()];
121
- }
122
-
123
- /**
124
- * 默认技能扫描目录（按优先级从低到高排列，扫描时后者覆盖前者）：
125
- * claude(global→project) < cursor(global→project) < codex(global→project) < deepccc(global→project)
126
- * 其中 codex 全局包含 ~/.codex/skills（CLI 旧路径）与 ~/.agents/skills（标准全局目录）。
127
- */
128
- export function buildDefaultSkillDirs(cwd: string): SkillDirSpec[] {
129
- const h = homedir();
130
- return [
131
- { dir: join(h, ".claude", "skills"), source: "claude", scope: "global" },
132
- { dir: join(cwd, ".claude", "skills"), source: "claude", scope: "project" },
133
- { dir: join(h, ".cursor", "skills"), source: "cursor", scope: "global" },
134
- { dir: join(cwd, ".cursor", "skills"), source: "cursor", scope: "project" },
135
- { dir: join(h, ".codex", "skills"), source: "codex", scope: "global" },
136
- { dir: join(h, ".agents", "skills"), source: "codex", scope: "global" },
137
- { dir: join(cwd, ".codex", "skills"), source: "codex", scope: "project" },
138
- { dir: join(h, ".deepccc", "skills"), source: "deepccc", scope: "global" },
139
- { dir: join(cwd, ".deepccc", "skills"), source: "deepccc", scope: "project" },
140
- ];
141
- }
142
-
143
- /**
144
- * 生成 skill 索引提示词（注入 system prompt）。
145
- * 索引只含 name + description + 来源 + 路径，并指示模型在任务匹配时
146
- * 先用 read_file 读取 SKILL.md 全文再执行；同时声明"创建技能"约定
147
- * （模型在对话中应把新技能创建到 ~/.deepccc/skills 或项目 .deepccc/skills）。
148
- */
149
- export function buildSkillsIndexPrompt(skills: BuiltinSkill[]): string {
150
- if (skills.length === 0) return "";
151
-
152
- const lines = [
153
- "## Available Skills",
154
- "Skills are scanned in parallel from Claude/Codex/Cursor/DeepCCC skill directories.",
155
- "On name conflicts: DeepCCC > Codex > Cursor > Claude wins; within one source, project scope wins over global.",
156
- "When a user request matches a skill's description, first read its full SKILL.md with read_file, then follow the instructions in it exactly.",
157
- "",
158
- ...skills.map((s) => `- **${s.name}** [${s.source}:${s.scope}] (\`${s.skillPath}\`): ${s.description || "(no description)"}`),
159
- "",
160
- "## Creating Skills",
161
- "When the user asks to create a skill, create it as a Codex-style directory skill at",
162
- "~/.deepccc/skills/<name>/SKILL.md (global, default) or <cwd>/.deepccc/skills/<name>/SKILL.md (project, only when the user explicitly asks for a project-scoped skill).",
163
- "SKILL.md format:",
164
- "```",
165
- "---",
166
- "name: <skill-name>",
167
- "description: <one-line description>",
168
- "---",
169
- "",
170
- "<instructions>",
171
- "```",
172
- "New skills are picked up automatically on the next message (hot reload); no restart is needed.",
173
- ];
174
- return lines.join("\n");
175
- }
176
-
177
- /** 生成 Codex 结构的新技能 SKILL.md 模板（供 CLI skill create / 对话创建约定共用） */
178
- export function buildSkillTemplate(name: string, description: string): string {
179
- return [
180
- "---",
181
- `name: ${name}`,
182
- `description: ${description}`,
183
- "---",
184
- "",
185
- `# ${name}`,
186
- "",
187
- "<skill instructions>",
188
- "",
189
- ].join("\n");
190
- }
1
+ /**
2
+ * skills.ts — 多来源技能扫描（DeepCCC 统一入口）
3
+ *
4
+ * 并行扫描 Claude / Codex / Cursor / DeepCCC 四套目录式技能
5
+ * （<name>/SKILL.md + YAML frontmatter，三套生态同构）。
6
+ *
7
+ * 同名优先级（高 → 低）：deepccc > codex > cursor > claude；
8
+ * 同来源内：project（项目级）> global（用户级）。
9
+ * 目录列表按低 → 高排列，扫描时后者覆盖前者，天然实现优先级。
10
+ *
11
+ * 热加载：SKILL.md 内容带 mtime 缓存，文件变化时自动重读；
12
+ * 目录枚举每次都做（新技能目录立即被发现）。因此"创建技能 →
13
+ * 下一次对话自动生效"，无需重启，也无需常驻 watcher。
14
+ */
15
+
16
+ import { readdirSync } from "node:fs";
17
+ import { readFile, stat } from "node:fs/promises";
18
+ import { homedir } from "node:os";
19
+ import { join } from "node:path";
20
+
21
+ export type SkillSource = "deepccc" | "codex" | "cursor" | "claude";
22
+ export type SkillScope = "global" | "project";
23
+
24
+ export interface BuiltinSkill {
25
+ name: string;
26
+ description: string;
27
+ /** SKILL.md 的绝对路径 */
28
+ skillPath: string;
29
+ /** 来源（优先级 deepccc > codex > cursor > claude） */
30
+ source: SkillSource;
31
+ /** global = 用户级；project = 项目级（同来源内 project > global） */
32
+ scope: SkillScope;
33
+ }
34
+
35
+ export interface SkillDirSpec {
36
+ dir: string;
37
+ source: SkillSource;
38
+ scope: SkillScope;
39
+ }
40
+
41
+ /** 解析 SKILL.md frontmatter（兼容 CRLF），返回 name + description；无 frontmatter 返回 null */
42
+ export function parseSkillFrontmatter(
43
+ content: string,
44
+ ): { name: string; description: string } | null {
45
+ const match = /^---\r?\n([\s\S]*?)\r?\n---\s*(?:\r?\n|$)/.exec(content);
46
+ if (!match) return null;
47
+ const fm = match[1];
48
+ const nameMatch = /^name:\s*(.+?)\s*$/m.exec(fm);
49
+ if (!nameMatch) return null;
50
+ const descMatch = /^description:\s*(.+?)\s*$/m.exec(fm);
51
+ return {
52
+ name: nameMatch[1].trim(),
53
+ description: descMatch?.[1].trim() ?? "",
54
+ };
55
+ }
56
+
57
+ // ---------------------------------------------------------------------------
58
+ // mtime 热加载缓存：同一进程内重复扫描命中缓存（stat 校验），文件变化自动重读
59
+ // ---------------------------------------------------------------------------
60
+
61
+ const skillFileCache = new Map<string, { mtimeMs: number; content: string }>();
62
+
63
+ async function readSkillFile(skillPath: string): Promise<string | null> {
64
+ let st;
65
+ try {
66
+ st = await stat(skillPath);
67
+ } catch {
68
+ return null;
69
+ }
70
+ if (!st.isFile()) return null;
71
+ const cached = skillFileCache.get(skillPath);
72
+ if (cached && cached.mtimeMs === st.mtimeMs) return cached.content;
73
+ const content = await readFile(skillPath, "utf8");
74
+ skillFileCache.set(skillPath, { mtimeMs: st.mtimeMs, content });
75
+ return content;
76
+ }
77
+
78
+ /**
79
+ * 扫描多个 skill 目录（并行读取），按 name 去重。
80
+ * 同名技能：后面的 spec（高优先级）覆盖前面的（低优先级）。
81
+ * 隐藏目录（.system 等）和无 SKILL.md 的目录会被跳过；缺失目录跳过。
82
+ */
83
+ export async function scanSkillsDirs(dirs: SkillDirSpec[]): Promise<BuiltinSkill[]> {
84
+ const byName = new Map<string, BuiltinSkill>();
85
+
86
+ for (const spec of dirs) {
87
+ let entries;
88
+ try {
89
+ entries = readdirSync(spec.dir, { withFileTypes: true });
90
+ } catch {
91
+ continue; // 目录不存在或不可读：跳过
92
+ }
93
+
94
+ // 目录内所有候选 SKILL.md 并行读取（读文件是扫描的瓶颈）
95
+ const results = await Promise.all(
96
+ entries
97
+ .filter((entry) => entry.isDirectory() && !entry.name.startsWith("."))
98
+ .map(async (entry) => {
99
+ const skillPath = join(spec.dir, entry.name, "SKILL.md");
100
+ const content = await readSkillFile(skillPath);
101
+ if (content === null) return null;
102
+ const parsed = parseSkillFrontmatter(content);
103
+ if (!parsed) return null;
104
+ return { ...parsed, skillPath };
105
+ }),
106
+ );
107
+
108
+ for (const result of results) {
109
+ if (!result) continue;
110
+ byName.set(result.name, {
111
+ name: result.name,
112
+ description: result.description,
113
+ skillPath: result.skillPath,
114
+ source: spec.source,
115
+ scope: spec.scope,
116
+ });
117
+ }
118
+ }
119
+
120
+ return [...byName.values()];
121
+ }
122
+
123
+ /**
124
+ * 默认技能扫描目录（按优先级从低到高排列，扫描时后者覆盖前者）：
125
+ * claude(global→project) < cursor(global→project) < codex(global→project) < deepccc(global→project)
126
+ * 其中 codex 全局包含 ~/.codex/skills（CLI 旧路径）与 ~/.agents/skills（标准全局目录）。
127
+ */
128
+ export function buildDefaultSkillDirs(cwd: string): SkillDirSpec[] {
129
+ const h = homedir();
130
+ return [
131
+ { dir: join(h, ".claude", "skills"), source: "claude", scope: "global" },
132
+ { dir: join(cwd, ".claude", "skills"), source: "claude", scope: "project" },
133
+ { dir: join(h, ".cursor", "skills"), source: "cursor", scope: "global" },
134
+ { dir: join(cwd, ".cursor", "skills"), source: "cursor", scope: "project" },
135
+ { dir: join(h, ".codex", "skills"), source: "codex", scope: "global" },
136
+ { dir: join(h, ".agents", "skills"), source: "codex", scope: "global" },
137
+ { dir: join(cwd, ".codex", "skills"), source: "codex", scope: "project" },
138
+ { dir: join(h, ".deepccc", "skills"), source: "deepccc", scope: "global" },
139
+ { dir: join(cwd, ".deepccc", "skills"), source: "deepccc", scope: "project" },
140
+ ];
141
+ }
142
+
143
+ /**
144
+ * 生成 skill 索引提示词（注入 system prompt）。
145
+ * 索引只含 name + description + 来源 + 路径，并指示模型在任务匹配时
146
+ * 先用 read_file 读取 SKILL.md 全文再执行；同时声明"创建技能"约定
147
+ * （模型在对话中应把新技能创建到 ~/.deepccc/skills 或项目 .deepccc/skills）。
148
+ */
149
+ export function buildSkillsIndexPrompt(skills: BuiltinSkill[]): string {
150
+ if (skills.length === 0) return "";
151
+
152
+ const lines = [
153
+ "## Available Skills",
154
+ "Skills are scanned in parallel from Claude/Codex/Cursor/DeepCCC skill directories.",
155
+ "On name conflicts: DeepCCC > Codex > Cursor > Claude wins; within one source, project scope wins over global.",
156
+ "When a user request matches a skill's description, first read its full SKILL.md with read_file, then follow the instructions in it exactly.",
157
+ "",
158
+ ...skills.map((s) => `- **${s.name}** [${s.source}:${s.scope}] (\`${s.skillPath}\`): ${s.description || "(no description)"}`),
159
+ "",
160
+ "## Creating Skills",
161
+ "When the user asks to create a skill, create it as a Codex-style directory skill at",
162
+ "~/.deepccc/skills/<name>/SKILL.md (global, default) or <cwd>/.deepccc/skills/<name>/SKILL.md (project, only when the user explicitly asks for a project-scoped skill).",
163
+ "SKILL.md format:",
164
+ "```",
165
+ "---",
166
+ "name: <skill-name>",
167
+ "description: <one-line description>",
168
+ "---",
169
+ "",
170
+ "<instructions>",
171
+ "```",
172
+ "New skills are picked up automatically on the next message (hot reload); no restart is needed.",
173
+ ];
174
+ return lines.join("\n");
175
+ }
176
+
177
+ /** 生成 Codex 结构的新技能 SKILL.md 模板（供 CLI skill create / 对话创建约定共用） */
178
+ export function buildSkillTemplate(name: string, description: string): string {
179
+ return [
180
+ "---",
181
+ `name: ${name}`,
182
+ `description: ${description}`,
183
+ "---",
184
+ "",
185
+ `# ${name}`,
186
+ "",
187
+ "<skill instructions>",
188
+ "",
189
+ ].join("\n");
190
+ }