@archon-claw/cli 0.5.0 → 0.5.1

package/dist/templates/workspace/.claude/skills/create-mcp-config/SKILL.md

@@ -1,151 +0,0 @@
----
-name: create-mcp-config
-description: 创建或修改 MCP 服务器配置文件。当用户需要连接外部 MCP 服务器、添加 MCP 工具时使用。
----
-
-创建或修改 `agents/my-agent/mcp.json` MCP 服务器配置文件。
-
-## 规范
-
-- 文件位于 Agent 配置文件夹根目录，文件名固定为 `mcp.json`
-- 该文件是可选的，不存在时 agent 只使用本地工具
-- MCP 工具会自动合并到 agent 的工具列表中，与本地工具无区别
-
-## 字段
-
-### 顶层
-
-| 字段 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| `mcpServers` | object | 是 | 服务器配置，key 为服务器名称 |
-
-### 每个 server 配置
-
-| 字段 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| `command` | string | stdio 时必填 | 可执行命令 |
-| `args` | string[] | 否 | 命令行参数 |
-| `env` | object | 否 | 环境变量，支持 `${VAR}` 引用 process.env |
-| `cwd` | string | 否 | 工作目录 |
-| `url` | string | SSE/HTTP 时必填 | 远程服务器 URL |
-| `headers` | object | 否 | HTTP 请求头 |
-| `transport` | string | 否 | `"stdio"` / `"sse"` / `"streamable-http"`，可自动推断 |
-| `enabled` | boolean | 否 | 设为 `false` 可禁用，默认 `true` |
-| `timeout` | number | 否 | 工具调用超时（毫秒），默认 30000 |
-| `tools` | object | 否 | 工具过滤配置 |
-
-### tools 过滤
-
-| 字段 | 类型 | 说明 |
-|------|------|------|
-| `include` | string[] | glob 模式白名单，只暴露匹配的工具 |
-| `exclude` | string[] | glob 模式黑名单，隐藏匹配的工具 |
-| `rename` | object | 重命名映射，如 `{"browser_navigate": "goto"}` |
-
-## Transport 自动推断
-
-- 有 `command` → `stdio`（本地进程通信）
-- 有 `url` → 先尝试 `streamable-http`，失败后自动 fallback 到 `sse`
-- 显式指定 `transport` 可跳过自动推断（如确定只用 SSE 时写 `"transport": "sse"`）
-- `command` 和 `url` 至少提供一个
-
-## 工具命名规则
-
-- 默认名称格式：`{serverName}__{toolName}`（避免冲突）
-- 通过 `rename` 可自定义名称（不加前缀）
-- 名称会自动规范化为 `^[a-z][a-z0-9_]*$`
-
-## 示例
-
-### 本地 stdio 服务器
-
-```json
-{
-  "mcpServers": {
-    "playwright": {
-      "command": "npx",
-      "args": ["@playwright/mcp@latest"],
-      "timeout": 60000,
-      "tools": {
-        "include": ["browser_*"],
-        "exclude": ["browser_install"]
-      }
-    }
-  }
-}
-```
-
-### 远程服务器（自动协商协议）
-
-只需提供 `url`，会先尝试 streamable-http，不支持则自动降级为 SSE：
-
-```json
-{
-  "mcpServers": {
-    "remote_api": {
-      "url": "https://my-server.com/mcp",
-      "headers": {
-        "Authorization": "Bearer ${API_TOKEN}"
-      }
-    }
-  }
-}
-```
-
-### 强制指定 SSE
-
-如果确定服务器只支持 SSE，可显式指定以跳过 streamable-http 尝试：
-
-```json
-{
-  "mcpServers": {
-    "legacy": {
-      "transport": "sse",
-      "url": "https://old-server.com/sse"
-    }
-  }
-}
-```
-
-### 多服务器配置
-
-```json
-{
-  "mcpServers": {
-    "filesystem": {
-      "command": "npx",
-      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"]
-    },
-    "github": {
-      "command": "npx",
-      "args": ["-y", "@modelcontextprotocol/server-github"],
-      "env": {
-        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
-      }
-    }
-  }
-}
-```
-
-## 在系统提示词中引用 MCP 工具
-
-MCP 服务器和工具会自动注入到 `system-prompt.md` 的 Liquid 模板变量 `mcp` 中，可按服务器名称访问：
-
-```markdown
-{% for tool in mcp.playwright.tools %}
-- {{ tool.name }}：{{ tool.description }}
-{% endfor %}
-```
-
-详见 `/create-system-prompt` 技能中的 `mcp 变量` 部分。
-
-## 注意
-
-- `command` 和 `url` 至少提供一个，否则校验失败
-- 环境变量中的敏感信息（API Key 等）用 `${VAR}` 引用，不要硬编码
-- 服务器连接失败不会阻止 agent 启动，只会打印警告
-- MCP 工具与本地工具同名时，本地工具优先（MCP 工具被跳过并打印警告）
-- 不要添加未定义的字段（strict 模式）
-- `mcpServers` 的 key（服务器名称）会作为 `mcp.{name}` 暴露给系统提示词模板
-
-请根据用户的需求创建或修改 MCP 配置。$ARGUMENTS

package/dist/templates/workspace/.claude/skills/create-model-config/SKILL.md

@@ -1,45 +0,0 @@
----
-name: create-model-config
-description: 创建或修改模型配置文件。当用户需要配置 LLM 模型、修改 model.json 时使用。
----
-
-创建或修改 `agents/my-agent/model.json` 模型配置文件。
-
-## 规范
-
-- 文件位于 Agent 配置文件夹根目录
-- 必须通过 `src/schemas/model.schema.json` 的校验
-
-## 字段
-
-| 字段 | 类型 | 必填 | 默认值 | 说明 |
-|------|------|------|--------|------|
-| `provider` | string | 是 | - | `"anthropic"` 或 `"openai"` |
-| `model` | string | 是 | - | 模型 ID |
-| `maxTokens` | number | 否 | 4096 | 最大输出 token 数 |
-| `temperature` | number | 否 | 0.7 | 采样温度，0~2 |
-| `apiKey` | string | 否 | - | API Key，优先用环境变量 |
-
-## 常用模型 ID
-
-Anthropic: `claude-sonnet-4-20250514`、`claude-opus-4-20250514`、`claude-haiku-4-5-20251001`
-OpenAI: `gpt-4o`、`gpt-4o-mini`
-
-## 示例
-
-```json
-{
-  "provider": "anthropic",
-  "model": "claude-sonnet-4-20250514",
-  "maxTokens": 4096,
-  "temperature": 0.7
-}
-```
-
-## 注意
-
-- `provider` 和 `model` 必填
-- `apiKey` 建议不写在文件里，用环境变量（`ANTHROPIC_API_KEY` / `OPENAI_API_KEY`）
-- 不要添加未定义的字段（`additionalProperties: false`）
-
-请根据用户的需求创建或修改模型配置。$ARGUMENTS

package/dist/templates/workspace/.claude/skills/create-skill/SKILL.md

@@ -1,63 +0,0 @@
----
-name: create-skill
-description: 创建 agent skill 技能。当用户需要为 agent 添加新的技能（如代码审查、解释代码等）时使用。
----
-
-在 `agents/my-agent/skills/` 目录下创建一个新的技能。
-
-## 规范
-
-- 创建 `skills/<skill-name>/SKILL.md` 文件
-- 必须通过 `src/schemas/agent-skill.schema.json` 的校验
-- frontmatter 必须包含 `name` 和 `description`
-- body 不能为空
-
-## 文件结构
-
-```
-skills/
-└── <skill-name>/
-    └── SKILL.md
-```
-
-## 格式
-
-```markdown
----
-name: skill-name
-description: 技能描述，说明什么场景下使用
----
-
-技能的具体指令内容...
-```
-
-## frontmatter 字段
-
-| 字段 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| `name` | string | 是 | 技能名称 |
-| `description` | string | 是 | 技能用途描述 |
-
-## 示例
-
-```markdown
----
-name: code-review
-description: 对代码进行 review，检查潜在问题并给出改进建议
----
-
-对用户提供的代码进行审查，关注以下方面：
-
-1. **正确性**：逻辑是否正确
-2. **安全性**：是否有安全隐患
-3. **性能**：是否有明显的性能问题
-4. **可读性**：命名是否清晰
-```
-
-## 注意
-
-- `name` 和 `description` 都是必填的
-- body 内容是技能的具体指令，不能为空
-- 不要添加 `name` 和 `description` 以外的 frontmatter 字段
-
-请根据用户需求创建技能。$ARGUMENTS

package/dist/templates/workspace/.claude/skills/create-system-prompt/SKILL.md

@@ -1,168 +0,0 @@
----
-name: create-system-prompt
-description: 创建或修改系统提示词。当用户需要编写 system-prompt.md 时使用。
----
-
-创建或修改 agent 的 `system-prompt.md` 系统提示词文件。
-
-## 规范
-
-- 文件位于 agent 配置文件夹根目录
-- 内容不能为空
-- 支持 Liquid 模板语法引用 datasets/ 和 skills/ 中的数据
-- 模板语法会在启动时由 liquidjs 解析验证
-
-## Liquid 模板变量
-
-### datasets 变量
-
-datasets/ 中的文件名（去掉 `.json`）即为变量名：
-
-```markdown
-{% for rule in rules %}
-- {{ rule }}
-{% endfor %}
-```
-
-### skills 变量
-
-skills/ 中的技能会自动注入为 `skills` 数组，每个元素包含 `name` 和 `description`：
-
-```markdown
-{% for skill in skills %}
-- **{{ skill.name }}**：{{ skill.description }}
-{% endfor %}
-```
-
-### tools / tool 变量
-
-所有工具（本地 + MCP）提供两种访问方式：
-
-- `tools` — 数组，用于遍历
-- `tool` — 对象（map），按名字直接访问
-
-```markdown
-{# 数组遍历 #}
-{% for tool in tools %}
-- **{{ tool.name }}**：{{ tool.description }}
-{% endfor %}
-
-{# 按名字访问 #}
-{{ tool.search.description }}
-```
-
-### mcp 变量
-
-mcp.json 中配置的 MCP 服务器和工具，按服务器名称分组访问：
-
-每个服务器也提供 `tools`（数组）和 `tool`（对象）两种形式：
-
-**遍历特定服务器的工具：**
-
-```markdown
-{% for tool in mcp.playwright.tools %}
-- {{ tool.name }}：{{ tool.description }}
-{% endfor %}
-```
-
-**按名字访问特定工具：**
-
-```markdown
-{{ mcp.playwright.tool.playwright__browser_click.description }}
-```
-
-**遍历所有服务器：**
-
-```markdown
-{% for server in mcp.servers %}
-### {{ server.name }}
-{% for tool in server.tools %}
-- {{ tool.name }}：{{ tool.description }}
-{% endfor %}
-{% endfor %}
-```
-
-**访问服务器名称：**
-
-```markdown
-{{ mcp.playwright.name }}
-```
-
-> `mcp.{serverName}` 中的 serverName 对应 mcp.json 里 `mcpServers` 的 key。
-
-## Liquid 模板语法
-
-### 遍历对象数组
-
-```markdown
-{% for item in examples %}
-### 问：{{ item.input }}
-{{ item.output }}
-{% endfor %}
-```
-
-### 条件判断
-
-```markdown
-{% if greeting %}
-{{ greeting }}
-{% endif %}
-```
-
-## 示例
-
-```markdown
-你是一个专业的编程助手。
-
-## 规则
-
-{% for rule in rules %}
-- {{ rule }}
-{% endfor %}
-
-## 可用技能
-
-{% for skill in skills %}
-- **{{ skill.name }}**：{{ skill.description }}
-{% endfor %}
-
-## 可用工具
-
-{% for tool in tools %}
-- **{{ tool.name }}**：{{ tool.description }}
-{% endfor %}
-
-## 浏览器工具
-
-{% for tool in mcp.playwright.tools %}
-- {{ tool.name }}：{{ tool.description }}
-{% endfor %}
-
-## 示例
-
-{% for item in examples %}
-### 问：{{ item.input }}
-
-{{ item.output }}
-
-{% endfor %}
-```
-
-## 写作建议
-
-1. 开头明确 agent 的角色定位
-2. 用 Markdown 标题组织结构（# 角色、## 规则、## 技能、## 示例）
-3. 规则用列表形式，简洁明了
-4. few-shot 示例放在 datasets/ 中通过模板引用，保持文件整洁
-5. 避免在提示词中硬编码大量数据，用 datasets 管理
-6. 用 `skills` 变量列出可用技能，让 agent 知道自己能做什么
-7. 用 `tools` 变量列出所有工具，用 `mcp.{serverName}.tools` 按服务器分类展示 MCP 工具
-
-## 注意
-
-- 不要使用 YAML frontmatter（system-prompt.md 不需要）
-- Liquid 标签必须正确闭合（`{% for %}...{% endfor %}`、`{% if %}...{% endif %}`）
-- datasets 模板变量名必须和 datasets/ 中的文件名一致
-- `skills`、`tools`、`tool`、`mcp` 是内置变量名，不要在 datasets/ 中创建同名文件
-
-请根据用户需求创建或修改系统提示词。$ARGUMENTS

package/dist/templates/workspace/.claude/skills/create-tool/SKILL.md

@@ -1,56 +0,0 @@
----
-name: create-tool
-description: 创建工具定义 JSON 文件。当用户需要新增一个 tool、定义工具 schema 时使用。
-argument-hint: "[tool_name]"
----
-
-在 `agents/my-agent/tools/` 目录下创建一个新的工具定义 JSON 文件。
-
-## 规范
-
-- 文件名与工具 `name` 一致，如 `send_email.json`
-- 必须通过 `src/schemas/tool.schema.json` 的校验
-
-## 必填字段
-
-- `name`：工具名称，匹配 `^[a-z][a-z0-9_]*$`
-- `description`：工具用途描述，要让模型理解何时调用
-- `input_schema`：入参定义，JSON Schema object 子集
-
-## input_schema 规范
-
-- `type` 必须为 `"object"`
-- `properties` 中每个参数必须有 `type`（string / number / boolean / array / object）
-- 建议每个参数写 `description`
-- 可选：`enum`、`items`（array 子项）、`required`（必填参数列表）
-
-## 示例
-
-```json
-{
-  "name": "web_search",
-  "description": "Search the web and return relevant results for a given query",
-  "input_schema": {
-    "type": "object",
-    "properties": {
-      "query": {
-        "type": "string",
-        "description": "The search query"
-      },
-      "limit": {
-        "type": "number",
-        "description": "Maximum number of results to return"
-      }
-    },
-    "required": ["query"]
-  }
-}
-```
-
-## 注意
-
-- 一个文件只定义一个工具
-- `required` 只列真正必须的参数
-- 不要添加 `name`、`description`、`input_schema` 以外的字段
-
-请根据用户的需求创建工具定义文件。$ARGUMENTS

package/dist/templates/workspace/.claude/skills/create-tool-impl/SKILL.md

@@ -1,83 +0,0 @@
----
-name: create-tool-impl
-description: 创建工具实现文件。当用户需要为 tool 编写具体的实现代码时使用。
-argument-hint: "[tool_name]"
----
-
-在 `agents/my-agent/tool-impls/` 目录下创建工具实现文件。
-
-## 规范
-
-- 文件名格式：`<tool-name>.impl.js`，与 `tools/<tool-name>.json` 一一对应
-- ES6 模块语法，`export default async function`
-- 函数接收参数对象，参数与对应 tool JSON 的 `input_schema.properties` 一致
-- 返回 Promise<object>
-
-## 文件结构
-
-```
-tool-impls/
-└── <tool-name>.impl.js    ← 与 tools/<tool-name>.json 对应
-```
-
-## 模板
-
-```javascript
-/**
- * <Tool description>
- * @param {object} params
- * @param {<type>} params.<param_name> - <param description>
- * @returns {Promise<object>} <return description>
- */
-export default async ({ param1, param2 }) => {
-  // 实现逻辑
-  return { result: "..." };
-};
-```
-
-## 示例
-
-### 搜索工具（对应 tools/search.json）
-
-```javascript
-/**
- * Search tool implementation
- * @param {object} params
- * @param {string} params.query - Search query
- * @returns {Promise<object>} Search results
- */
-export default async ({ query }) => {
-  // TODO: integrate with real search API
-  return {
-    results: [
-      { title: `Result for: ${query}`, url: "https://example.com" },
-    ],
-  };
-};
-```
-
-### 计算器（对应 tools/calculator.json）
-
-```javascript
-/**
- * Calculator tool implementation
- * @param {object} params
- * @param {string} params.expression - Mathematical expression
- * @returns {Promise<object>} Calculation result
- */
-export default async ({ expression }) => {
-  const result = Function(`"use strict"; return (${expression})`)();
-  return { expression, result };
-};
-```
-
-## 注意
-
-- 文件名必须是 `<tool-name>.impl.js`，其中 `<tool-name>` 与 tools/ 中的 JSON 文件名一致
-- 函数参数通过解构获取，参数名与 tool JSON 中 `input_schema.properties` 的 key 一致
-- 必须使用 `export default`，不能用 `module.exports`
-- 函数必须是 async 的，返回对象
-- 用 JSDoc 注释描述参数和返回值
-- 每个 tool 必须有且仅有一个对应的 impl 文件
-
-请根据用户的需求创建工具实现文件。$ARGUMENTS

package/dist/templates/workspace/.claude/skills/create-tool-test/SKILL.md

@@ -1,117 +0,0 @@
----
-name: create-tool-test
-description: 创建工具测试文件。当用户需要为 tool-impl 编写测试用例时使用。
-argument-hint: "[tool_name]"
----
-
-在 `agents/my-agent/tests/` 目录下创建工具测试文件。
-
-## 规范
-
-- 文件名格式：`<tool-name>.test.js`，与 `tool-impls/<tool-name>.impl.js` 一一对应
-- ES6 模块语法，`export default` 导出测试用例数组
-- 每个测试用例是一个对象，包含 `name`、`args`，以及可选的 `expected` 或 `validate`
-- 通过 `archon-claw test <agent-dir>` 命令运行
-
-## 文件结构
-
-```
-agents/<agent-name>/
-├── tool-impls/
-│   └── <tool-name>.impl.js     ← 工具实现
-└── tests/
-    └── <tool-name>.test.js      ← 对应的测试文件
-```
-
-## 测试用例字段
-
-| 字段 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| `name` | string | 是 | 测试名称，描述测试内容 |
-| `args` | object | 是 | 传给 impl 函数的参数 |
-| `expected` | any | 否 | 期望返回值，深度比较 |
-| `validate` | function | 否 | 自定义校验函数 |
-
-### 三种断言方式
-
-1. **`expected`** — 精确匹配返回值（深度比较）
-2. **`validate(result)`** — 自定义校验，返回 `true` 表示通过，返回字符串表示失败原因
-3. **都不写** — 只验证调用不抛异常
-
-## 模板
-
-```javascript
-export default [
-  {
-    name: "描述测试内容",
-    args: { param1: "value1" },
-    expected: { result: "expected_value" },
-  },
-  {
-    name: "自定义校验",
-    args: { param1: "value1" },
-    validate: (result) =>
-      result.field === "expected" || `expected "expected", got "${result.field}"`,
-  },
-  {
-    name: "只要不抛异常就通过",
-    args: { param1: "value1" },
-  },
-];
-```
-
-## 示例
-
-### 计算器测试（对应 tool-impls/calculator.impl.js）
-
-```javascript
-export default [
-  {
-    name: "addition: 1 + 2 = 3",
-    args: { expression: "1 + 2" },
-    expected: { expression: "1 + 2", result: 3 },
-  },
-  {
-    name: "complex expression",
-    args: { expression: "(10 + 5) * 2 - 4" },
-    validate: (result) => result.result === 26 || `expected 26, got ${result.result}`,
-  },
-];
-```
-
-### 搜索测试（对应 tool-impls/search.impl.js）
-
-```javascript
-export default [
-  {
-    name: "returns results array",
-    args: { query: "hello" },
-    validate: (result) =>
-      Array.isArray(result.results) || "expected results to be an array",
-  },
-  {
-    name: "result contains query in title",
-    args: { query: "test query" },
-    validate: (result) =>
-      result.results[0]?.title.includes("test query") ||
-      `expected title to contain "test query"`,
-  },
-];
-```
-
-## 运行测试
-
-```bash
-archon-claw test agents/my-agent
-```
-
-## 注意
-
-- 测试文件放在 `tests/` 目录，与 `tool-impls/` 同级
-- 文件名必须是 `<tool-name>.test.js`，其中 `<tool-name>` 与 `tool-impls/` 中的 `.impl.js` 文件名一致
-- 必须使用 `export default`，导出数组
-- 每个用例必须有 `name` 和 `args`
-- `validate` 函数返回 `true` 或错误消息字符串
-- `expected` 和 `validate` 二选一，都不写则只检查不抛异常
-
-请根据用户的需求创建工具测试文件。$ARGUMENTS