@migor/cli 0.2.1 → 0.3.0

package/dist/templates.js

@@ -14,16 +14,31 @@ export function kebabToPascal(name) {
 export function kebabToSnake(name) {
     return name.replace(/-/g, '_');
 }
-export const UNIT_TYPES = ['tool', 'skill', 'prompt', 'subagent'];
-export function isUnitType(value) {
-    return UNIT_TYPES.includes(value);
+export const CAPABILITY_TYPES = ['tool', 'skill', 'prompt', 'subagent'];
+export function isCapabilityType(value) {
+    return CAPABILITY_TYPES.includes(value);
 }
-// ---------- units.ts 注册表模板 ----------
+// ---------- 目录约定（spec §7：四分类目录，一能力一文件夹，无伞形词） ----------
+/**
+ * 能力类型 → 分类目录。目录名即「里面装什么」，不再用一个需要图例解释的伞形词：
+ * 用户看一眼 `src/tools/weather/index.ts` 就知道它是工具。
+ */
+export const CAPABILITY_DIRS = {
+    tool: 'src/tools',
+    skill: 'src/skills',
+    prompt: 'src/prompts',
+    subagent: 'src/subagents',
+};
+/** 全部能力目录（顺序即 discover 的装配顺序） */
+export const CAPABILITY_DIR_LIST = CAPABILITY_TYPES.map((t) => CAPABILITY_DIRS[t]);
+/** 显式注册表位置（`agentia g` / `agentia add` 维护，`agentia doctor` 校验） */
+export const REGISTRY_PATH = 'src/registry.ts';
+// ---------- 注册表模板 ----------
 export const IMPORTS_END_MARKER = '// @agentia:imports-end';
 export const ENTRIES_END_MARKER = '// @agentia:entries-end';
-/** 空注册表模板（无任何单元条目） */
+/** 空注册表模板（无任何能力条目） */
 export function emptyRegistryTemplate() {
-    return `// Agentia 单元注册表 —— 由 agentia CLI 维护（agentia g 自动更新，也可手工编辑）
+    return `// Agentia 能力注册表 —— 由 agentia CLI 维护（agentia g 自动更新，也可手工编辑）
 // @agentia:imports
 ${IMPORTS_END_MARKER}
 import type { Provider } from '@migor/agentia';
@@ -45,7 +60,7 @@ export function projectPackageJson(name) {
             dev: 'tsx src/main.ts',
             typecheck: 'tsc --noEmit -p tsconfig.json',
         },
-        dependencies: { '@migor/agentia': '^0.2.0' },
+        dependencies: { '@migor/agentia': '^0.3.0' },
         devDependencies: {
             tsx: '^4.19.0',
             typescript: '^7.0.2',
@@ -64,78 +79,129 @@ export function projectTsconfig() {
             esModuleInterop: true,
             skipLibCheck: true,
         },
-        include: ['src', 'units.ts'],
+        include: ['src'],
     }, null, 2)}\n`;
 }
 export function mainTs(name) {
-    return `import { createApp, SystemPrompt } from '@migor/agentia';
+    return `import { createApp, loadEnvFile, SystemPrompt } from '@migor/agentia';
+
+// 读同目录的 .env（key 写文件里即可，不必每次 export）。框架**不自动**读 .env ——
+// 读哪个文件、什么时候读由这里决定；已存在的真实环境变量优先，不会被文件覆盖。
+// 想换路径/顺序：loadEnvFile({ path: '.env.local' }) 或直接删掉这一行改用自己的加载器。
+loadEnvFile();
 
 const app = await createApp({
   name: '${name}',
-  discover: 'units', // 目录约定：units/<name>/ 一单元一文件夹，启动期扫描装配
-  system: new SystemPrompt().add('role', '你是 ${name} 的主 agent，按任务自主调度菜单里的单元。', true),
+  discover: [${CAPABILITY_DIR_LIST.map((p) => `'${p}'`).join(', ')}], // 四分类目录，顺序即装配顺序
+  system: new SystemPrompt().add('role', '你是 ${name} 的主 agent，按任务自主调度菜单里的能力。', true),
 });
 
 const { result } = await app.run(
   [{ role: 'user', content: process.argv[2] ?? '介绍一下你自己' }],
 );
-console.log(result.finalText);
+
+// 注意：run 失败**不会抛**（硬失败被记进 result.error 与 trace 后正常返回）—— 不显式检查就会
+// 「打印一行空白 + 退出 0」，让首次运行（比如忘了配 ANTHROPIC_API_KEY）看起来像成功。
+if (result.error) {
+  console.error(\`run 失败（stopReason=\${result.stopReason}）：\${result.error.message}\`);
+  console.error('提示：模型调用读 ANTHROPIC_API_KEY —— 填进 .env（首行 loadEnvFile() 会读）或 export 均可；');
+  console.error('      换端点 / 注入自定义 client 见项目内 AGENTS.md。');
+  process.exitCode = 1;
+}
+if (result.finalText) console.log(result.finalText);
 `;
 }
 export function projectReadme(name) {
     return `# ${name}
 
-基于 [Agentia](https://github.com/) 框架的 agent 应用。
+基于 [Agentia](https://github.com/retrychx/agentia) 框架的 agent 应用。
 
 ## 目录约定
 
-\`units/<name>/\` 一单元一文件夹，每个单元是一个 default export 的类，用装饰器声明能力：
+四分类目录，一能力一文件夹，每个能力是一个 default export 的类，用装饰器声明：
 
-- \`@Tool\` 工具：主 agent 可调用（input → value）
-- \`@Skill\` 技能：方法体内通过 \`ctx.llm()\` 调 LLM
-- \`@SubAgent\` 子代理：按 system 角色设定独立跑一轮
-- \`@Prompt\` 文本资产：.md 文件，按需拉取进上下文
+- \`src/tools/<name>/\` —— \`@Tool\` 工具：主 agent 可调用（input → value）
+- \`src/skills/<name>/\` —— \`@Skill\` 技能：方法体内通过 \`ctx.llm()\` 调 LLM
+- \`src/subagents/<name>/\` —— \`@SubAgent\` 子代理：按 system 角色设定独立跑一轮
+- \`src/prompts/<name>/\` —— \`@Prompt\` 文本资产：.md 文件，按需拉取进上下文
+
+目录名就是类型，不用记别名。
 
 ## 两条装配路线
 
-1. **目录扫描**：\`createApp({ discover: 'units' })\` 启动期扫描 \`units/*/index.ts\`，default export 为类时以文件夹名为 DI token 注册（见 \`src/main.ts\`）。
-2. **显式装配**：\`createApp({ providers, system })\`，providers 来自 \`units.ts\` 注册表（由 \`agentia g\` 自动维护，也可手工编辑）。
+1. **目录扫描**：\`createApp({ discover: [...] })\` 启动期按给定顺序扫各目录下的 \`<name>/index.ts\`，default export 为类时以文件夹名为 DI token 注册（见 \`src/main.ts\`）。
+2. **显式装配**：\`createApp({ providers, system })\`，providers 来自 \`src/registry.ts\` 注册表（由 \`agentia g\` 自动维护，也可手工编辑）。
 
 两者二选一或混用。
 
-## 生成单元
+## 生成能力
 
 \`\`\`bash
-agentia g tool my-tool        # 工具
-agentia g skill my-skill      # 技能
-agentia g prompt my-prompt    # 文本资产（含 asset.md）
-agentia g subagent my-agent   # 子代理（含 system.md）
+agentia g tool my-tool        # → src/tools/my-tool/
+agentia g skill my-skill      # → src/skills/my-skill/
+agentia g prompt my-prompt    # → src/prompts/my-prompt/（含 asset.md）
+agentia g subagent my-agent   # → src/subagents/my-agent/（含 system.md）
 \`\`\`
 
-生成的单元在 \`units/<name>/\`，并自动登记到 \`units.ts\`。
+生成的能力自动登记到 \`src/registry.ts\`。
 
 ## 运行
 
-需要 Anthropic API key：
+需要 Anthropic API key —— 填进脚手架已生成的 \`.env\` 即可（本文件在 \`.gitignore\` 里）：
+
+\`\`\`bash
+# .env
+ANTHROPIC_API_KEY=sk-ant-...
+\`\`\`
+
+\`\`\`bash
+npm run dev -- "你的问题"
+\`\`\`
+
+也可以用环境变量（适合 CI / 容器）——**真实环境变量优先，不会被 \`.env\` 覆盖**：
 
 \`\`\`bash
 export ANTHROPIC_API_KEY=sk-ant-...
 npm run dev -- "你的问题"
 \`\`\`
+
+\`.env\` 由 \`src/main.ts\` 首行的 \`loadEnvFile()\` 读取。框架**不会自动读**它 ——
+读哪个文件、什么时候读由你的启动代码决定（这样「换目录跑」不会悄悄改变行为）。
 `;
 }
 export function projectGitignore() {
     return `node_modules
 dist
+
+# 本地环境变量（可能含 key）—— 绝不提交
+.env
+.env.local
+`;
+}
+/** 脚手架生成的 .env：填上就能跑，已进 .gitignore */
+export function projectDotEnv() {
+    return `# 模型 API key —— 填上后 npm run dev / npm start 直接可用
+# 本文件已被 .gitignore 忽略：不要提交，也不要把 key 写进 README / AGENTS.md
+ANTHROPIC_API_KEY=
+`;
+}
+/** 随脚手架提交的 .env.example：进版本库的变量清单，值一律留空 */
+export function projectDotEnvExample() {
+    return `# 复制成 .env 再填值（.env 已 gitignore，不要提交）
+ANTHROPIC_API_KEY=
+
+# 可选
+# ANTHROPIC_BASE_URL=https://api.anthropic.com
+# AGENTIA_MODEL=claude-opus-5
 `;
 }
-// ---------- g 命令单元模板 ----------
+// ---------- g 命令能力模板 ----------
 export function toolIndexTs(name) {
     const cls = kebabToPascal(name);
     const method = kebabToSnake(name);
     return `import { Tool } from '@migor/agentia';
 
-/** ${name} 工具单元 */
+/** ${name} 工具能力 */
 export default class ${cls} {
   @Tool({
     description: '示例工具：回显输入',
@@ -158,7 +224,7 @@ export function promptIndexTs(name) {
     const method = kebabToSnake(name);
     return `import { Prompt, asset } from '@migor/agentia';
 
-/** ${name} 文本资产单元 */
+/** ${name} 文本资产能力 */
 export default class ${cls} {
   @Prompt({ description: '${name} 文本资产（描述何时该拉取）' })
   ${method}(): string {
@@ -178,7 +244,7 @@ export function subagentIndexTs(name) {
     const method = kebabToSnake(name);
     return `import { SubAgent, asset } from '@migor/agentia';
 
-/** ${name} 子代理单元 */
+/** ${name} 子代理能力 */
 export default class ${cls} {
   @SubAgent({
     description: '示例子代理：按 system.md 的角色设定独立处理任务',
@@ -207,7 +273,7 @@ export function skillIndexTs(name) {
     return `import { Skill } from '@migor/agentia';
 import type { SkillContext } from '@migor/agentia';
 
-/** ${name} 技能单元 */
+/** ${name} 技能能力 */
 export default class ${cls} {
   @Skill({
     description: '示例技能：就给定主题调用 LLM 产出要点',

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@migor/cli",
-  "version": "0.2.1",
-  "description": "Agentia 框架命令行工具：create 脚手架 + g 单元生成器",
+  "version": "0.3.0",
+  "description": "Agentia 框架命令行工具：create 脚手架 + g 能力生成 + dev 本地可观测面板（trace inspector）",
   "type": "module",
   "bin": {
     "agentia": "./dist/cli.js"
@@ -10,6 +10,11 @@
     "dist"
   ],
   "repository": "retrychx/agentia",
+  "homepage": "https://agentia-web.pages.dev",
+  "bugs": {
+    "url": "https://github.com/retrychx/agentia/issues"
+  },
+  "license": "MIT",
   "keywords": [
     "agentia",
     "agent",
@@ -24,7 +29,8 @@
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",
-    "prepublishOnly": "npm run build"
+    "test": "node --test \"test/*.test.mjs\"",
+    "prepublishOnly": "node ../../scripts/check-release.mjs && npm run build"
   },
   "devDependencies": {
     "@types/node": "^22.0.2",