chatccc 0.2.221 → 0.2.222

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chatccc",
-  "version": "0.2.221",
+  "version": "0.2.222",
   "description": "Feishu bot bridge for Claude Code",
   "license": "Apache-2.0",
   "type": "module",

package/src/__tests__/builtin-chat-session.test.ts

@@ -53,6 +53,46 @@ afterEach(() => {
   config.rawStreamLogs = structuredClone(originalRawStreamLogs);
 });
 
+describe("ChatSession codex-style skills", () => {
+  it("injects skill index into system prompt from skillsDirs", async () => {
+    const { ChatSession } = await import("../builtin/index.ts");
+    const dir = await mkdtemp(join(tmpdir(), "chatccc-session-skills-"));
+    const skillsDir = join(dir, ".codex", "skills");
+    await mkdir(join(skillsDir, "demo-skill"), { recursive: true });
+    await writeFile(
+      join(skillsDir, "demo-skill", "SKILL.md"),
+      "---\nname: demo-skill\ndescription: 演示技能\n---\n\n# 演示",
+      "utf-8",
+    );
+    streamTextMock.mockReturnValueOnce({ textStream: textStream() });
+
+    const session = new ChatSession(
+      { apiKey: "sk-test" },
+      { cwd: dir, sessionId: "skill-index", skillsDirs: [skillsDir] },
+    );
+    await collect(session.chat("hi"));
+
+    const system = streamTextMock.mock.calls.at(-1)?.[0].system as string;
+    expect(system).toContain("## Available Skills");
+    expect(system).toContain("demo-skill");
+    expect(system).toContain("演示技能");
+  });
+
+  it("skips skill injection when no skills are found", async () => {
+    const { ChatSession } = await import("../builtin/index.ts");
+    const dir = await mkdtemp(join(tmpdir(), "chatccc-session-no-skills-"));
+    streamTextMock.mockReturnValueOnce({ textStream: textStream() });
+
+    const session = new ChatSession(
+      { apiKey: "sk-test" },
+      { cwd: dir, sessionId: "no-skills", skillsDirs: [join(dir, "missing")] },
+    );
+    await collect(session.chat("hi"));
+
+    const system = streamTextMock.mock.calls.at(-1)?.[0].system as string;
+    expect(system).not.toContain("## Available Skills");
+  });
+});
 describe("ChatSession context management", () => {
   it("injects cwd project instruction files before runtime workspace details", async () => {
     const { ChatSession } = await import("../builtin/index.ts");

package/src/__tests__/builtin-skills.test.ts

@@ -0,0 +1,141 @@
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { afterEach, describe, expect, it } from "vitest";
+
+import {
+  buildSkillsIndexPrompt,
+  parseSkillFrontmatter,
+  scanSkillsDirs,
+} from "../builtin/skills.ts";
+
+const tempDirs: string[] = [];
+
+async function makeTempDir(): Promise<string> {
+  const dir = await mkdtemp(join(tmpdir(), "chatccc-skills-"));
+  tempDirs.push(dir);
+  return dir;
+}
+
+afterEach(async () => {
+  await Promise.all(tempDirs.splice(0).map((dir) => rm(dir, { recursive: true, force: true })));
+});
+
+describe("parseSkillFrontmatter", () => {
+  it("parses name and description from frontmatter", () => {
+    const content = [
+      "---",
+      "name: feishu-doc-download-md",
+      "description: 下载飞书文档为 Markdown",
+      "---",
+      "",
+      "# 正文",
+    ].join("\n");
+    expect(parseSkillFrontmatter(content)).toEqual({
+      name: "feishu-doc-download-md",
+      description: "下载飞书文档为 Markdown",
+    });
+  });
+
+  it("returns null when there is no frontmatter", () => {
+    expect(parseSkillFrontmatter("# just a heading")).toBeNull();
+  });
+
+  it("tolerates missing description", () => {
+    expect(parseSkillFrontmatter("---\nname: minimal-skill\n---\n\nbody")).toEqual({
+      name: "minimal-skill",
+      description: "",
+    });
+  });
+
+  it("handles CRLF line endings", () => {
+    const content = "---\r\nname: crlf-skill\r\ndescription: CRLF 描述\r\n---\r\n\r\nbody";
+    expect(parseSkillFrontmatter(content)).toEqual({
+      name: "crlf-skill",
+      description: "CRLF 描述",
+    });
+  });
+});
+
+describe("scanSkillsDirs", () => {
+  it("scans multiple dirs, skips hidden/system dirs, dedupes by name (later dir wins)", async () => {
+    const dir = await makeTempDir();
+    const userA = join(dir, "codex-skills");
+    const userB = join(dir, "agents-skills");
+    const project = join(dir, "project-codex");
+    await mkdir(join(userA, "feishu-doc"), { recursive: true });
+    await mkdir(join(userA, ".system"), { recursive: true });
+    await mkdir(join(userA, "no-skill-dir"));
+    await mkdir(join(userB, "feishu-doc"), { recursive: true });
+    await mkdir(join(userB, "another"), { recursive: true });
+    await mkdir(join(project, "feishu-doc"), { recursive: true });
+
+    await writeFile(
+      join(userA, "feishu-doc", "SKILL.md"),
+      "---\nname: feishu-doc\ndescription: 用户级 A\n---\n",
+      "utf8",
+    );
+    await writeFile(
+      join(userA, ".system", "SKILL.md"),
+      "---\nname: system-skill\ndescription: 内置\n---\n",
+      "utf8",
+    );
+    await writeFile(
+      join(userB, "feishu-doc", "SKILL.md"),
+      "---\nname: feishu-doc\ndescription: 用户级 B\n---\n",
+      "utf8",
+    );
+    await writeFile(
+      join(userB, "another", "SKILL.md"),
+      "---\nname: another\ndescription: 另一个\n---\n",
+      "utf8",
+    );
+    await writeFile(
+      join(project, "feishu-doc", "SKILL.md"),
+      "---\nname: feishu-doc\ndescription: 项目级覆盖\n---\n",
+      "utf8",
+    );
+
+    const skills = scanSkillsDirs([userA, userB, project]);
+
+    // 去重：同名保留一个，后面的目录（项目级）覆盖前面的（用户级）
+    expect(skills).toHaveLength(2);
+    const byName = new Map(skills.map((s) => [s.name, s]));
+    expect(byName.get("feishu-doc")?.description).toBe("项目级覆盖");
+    expect(byName.get("feishu-doc")?.skillPath).toBe(join(project, "feishu-doc", "SKILL.md"));
+    expect(byName.get("another")?.description).toBe("另一个");
+    expect(byName.has("system-skill")).toBe(false); // 隐藏目录被排除
+  });
+
+  it("skips missing directories and dirs without SKILL.md", async () => {
+    const dir = await makeTempDir();
+    await mkdir(join(dir, "empty-dir"));
+
+    const skills = scanSkillsDirs([join(dir, "missing-dir"), join(dir, "empty-dir")]);
+
+    expect(skills).toEqual([]);
+  });
+});
+
+describe("buildSkillsIndexPrompt", () => {
+  it("renders a skill index with names, paths and descriptions", () => {
+    const prompt = buildSkillsIndexPrompt([
+      {
+        name: "feishu-doc",
+        description: "下载飞书文档",
+        skillPath: "C:\\users\\x\\skills\\feishu-doc\\SKILL.md",
+      },
+    ]);
+
+    expect(prompt).toContain("## Available Skills");
+    expect(prompt).toContain("**feishu-doc**");
+    expect(prompt).toContain("下载飞书文档");
+    expect(prompt).toContain("C:\\users\\x\\skills\\feishu-doc\\SKILL.md");
+    expect(prompt).toContain("read_file");
+  });
+
+  it("returns empty string for no skills", () => {
+    expect(buildSkillsIndexPrompt([])).toBe("");
+  });
+});

package/src/builtin/index.ts

@@ -20,6 +20,7 @@ import {
   defaultBuiltinSessionId,
 } from "./context.ts";
 import { createBuiltinFileTools } from "./file-tools.ts";
+import { buildDefaultSkillDirs, buildSkillsIndexPrompt, scanSkillsDirs } from "./skills.ts";
 
 // ---------------------------------------------------------------------------
 // 系统提示词 — 编译期冻结常量
@@ -118,6 +119,11 @@ export interface ChatSessionOptions {
   keepRecentMessages?: number;
   /** Optional tool-step limit. Leave unset for no step limit. */
   maxSteps?: number;
+  /**
+   * Codex-style skill 扫描目录（<dir>/<name>/SKILL.md）。
+   * 缺省扫描 ~/.codex/skills、~/.agents/skills、<cwd>/.codex/skills。
+   */
+  skillsDirs?: string[];
 }
 
 /**
@@ -180,6 +186,12 @@ export class ChatSession {
     if (projectInstructions) {
       systemContent.push("", projectInstructions);
     }
+    // Codex-style skills 索引注入（name + description + 路径，模型按需 read_file 全文）
+    const skills = scanSkillsDirs(options.skillsDirs ?? buildDefaultSkillDirs(this.cwd));
+    const skillsPrompt = buildSkillsIndexPrompt(skills);
+    if (skillsPrompt) {
+      systemContent.push("", skillsPrompt);
+    }
     if (options.systemPrompt) {
       systemContent.push("", options.systemPrompt);
     }

package/src/builtin/skills.ts

@@ -0,0 +1,108 @@
+/**
+ * builtin/skills.ts — Codex-style skills 支持
+ *
+ * 从用户级（~/.codex/skills、~/.agents/skills）和项目级（<cwd>/.codex/skills）
+ * 扫描 Codex 目录式 skill（<name>/SKILL.md），解析 frontmatter 中的
+ * name + description，生成索引注入 system prompt。模型按需用 read_file
+ * 读取 SKILL.md 全文并执行（索引注入省 token，触发靠 description + 指令）。
+ */
+
+import { readFileSync, readdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+export interface BuiltinSkill {
+  name: string;
+  description: string;
+  /** SKILL.md 的绝对路径 */
+  skillPath: string;
+}
+
+/** 解析 SKILL.md frontmatter（兼容 CRLF），返回 name + description；无 frontmatter 返回 null */
+export function parseSkillFrontmatter(
+  content: string,
+): { name: string; description: string } | null {
+  const match = /^---\r?\n([\s\S]*?)\r?\n---\s*(?:\r?\n|$)/.exec(content);
+  if (!match) return null;
+  const fm = match[1];
+  const nameMatch = /^name:\s*(.+?)\s*$/m.exec(fm);
+  if (!nameMatch) return null;
+  const descMatch = /^description:\s*(.+?)\s*$/m.exec(fm);
+  return {
+    name: nameMatch[1].trim(),
+    description: descMatch?.[1].trim() ?? "",
+  };
+}
+
+/**
+ * 扫描多个 skill 目录，返回去重后的 skill 列表。
+ * 同名 skill 后面的目录覆盖前面的（调用方应把项目级目录放最后）。
+ * 隐藏目录（.system 等）和无 SKILL.md 的目录会被跳过。
+ */
+export function scanSkillsDirs(dirs: string[]): BuiltinSkill[] {
+  const byName = new Map<string, BuiltinSkill>();
+
+  for (const dir of dirs) {
+    let entries;
+    try {
+      entries = readdirSync(dir, { withFileTypes: true });
+    } catch {
+      continue; // 目录不存在或不可读：跳过
+    }
+
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      if (entry.name.startsWith(".")) continue; // 排除 .system 等隐藏/内置目录
+
+      const skillPath = join(dir, entry.name, "SKILL.md");
+      let content: string;
+      try {
+        content = readFileSync(skillPath, "utf-8");
+      } catch {
+        continue; // 没有 SKILL.md 的目录不是 skill
+      }
+
+      const parsed = parseSkillFrontmatter(content);
+      if (!parsed) continue;
+
+      byName.set(parsed.name, {
+        name: parsed.name,
+        description: parsed.description,
+        skillPath,
+      });
+    }
+  }
+
+  return [...byName.values()];
+}
+
+/**
+ * 默认 skill 扫描目录：
+ * 1. ~/.codex/skills（Codex CLI 旧路径，用户实际在用的地方）
+ * 2. ~/.agents/skills（Codex 标准全局目录）
+ * 3. <cwd>/.codex/skills（项目级，优先级最高，放最后）
+ */
+export function buildDefaultSkillDirs(cwd: string): string[] {
+  return [
+    join(homedir(), ".codex", "skills"),
+    join(homedir(), ".agents", "skills"),
+    join(cwd, ".codex", "skills"),
+  ];
+}
+
+/**
+ * 生成 skill 索引提示词（注入 system prompt）。
+ * 索引只含 name + description + 路径，并指示模型在任务匹配时
+ * 先用 read_file 读取 SKILL.md 全文再执行——这是触发率的关键。
+ */
+export function buildSkillsIndexPrompt(skills: BuiltinSkill[]): string {
+  if (skills.length === 0) return "";
+
+  const lines = [
+    "## Available Skills (Codex-style)",
+    "The following Codex-style skills are available on this machine. 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.",
+    "",
+    ...skills.map((s) => `- **${s.name}** (\`${s.skillPath}\`): ${s.description || "(no description)"}`),
+  ];
+  return lines.join("\n");
+}