@migor/cli 0.0.1

package/dist/cli.js

@@ -0,0 +1,79 @@
+#!/usr/bin/env node
+/** agentia CLI 入口：手写参数解析 + 命令分发（零依赖） */
+import { createProject } from './create.js';
+import { generateUnit } from './generate.js';
+import { isUnitType, isValidName, UNIT_TYPES } from './templates.js';
+import { RegistryError } from './registry.js';
+const USAGE = `agentia —— Agentia 框架命令行工具
+
+用法：
+  agentia create <name> [--dir <parent>]   创建项目脚手架（目录 <parent|当前目录>/<name>/）
+  agentia g <type> <name>                  在当前目录生成单元（别名：generate）
+                                           type: ${UNIT_TYPES.join(' | ')}
+  agentia --help                           显示本帮助
+
+name 规则：小写字母开头的小写 kebab-case（如 hello、doc-reviewer）
+`;
+function fail(message) {
+    console.error(`错误：${message}`);
+    process.exitCode = 1;
+    return 1;
+}
+function checkName(name) {
+    if (name === undefined)
+        return false;
+    return isValidName(name);
+}
+function main(argv) {
+    const [command, ...rest] = argv;
+    if (command === undefined || command === '--help' || command === '-h') {
+        console.log(USAGE);
+        return 0;
+    }
+    if (command === 'create') {
+        const name = rest[0];
+        let parent;
+        for (let i = 1; i < rest.length; i += 1) {
+            if (rest[i] === '--dir') {
+                parent = rest[i + 1];
+                if (parent === undefined)
+                    return fail('--dir 需要一个目录参数');
+                i += 1;
+            }
+            else {
+                return fail(`未知参数：${rest[i]}`);
+            }
+        }
+        if (name === undefined)
+            return fail('缺少项目名，用法：agentia create <name> [--dir <parent>]');
+        if (!checkName(name)) {
+            return fail(`非法项目名「${name}」：需匹配小写 kebab-case（如 my-app）`);
+        }
+        return createProject(name, parent);
+    }
+    if (command === 'g' || command === 'generate') {
+        const [type, name, ...extra] = rest;
+        if (type === undefined || name === undefined || extra.length > 0) {
+            return fail('用法：agentia g <type> <name>（type: tool | skill | prompt | subagent）');
+        }
+        if (!isUnitType(type)) {
+            return fail(`未知单元类型「${type}」，可选：${UNIT_TYPES.join(' | ')}`);
+        }
+        if (!checkName(name)) {
+            return fail(`非法单元名「${name}」：需匹配小写 kebab-case（如 doc-reviewer）`);
+        }
+        try {
+            return generateUnit(type, name);
+        }
+        catch (err) {
+            if (err instanceof RegistryError)
+                return fail(err.message);
+            throw err;
+        }
+    }
+    console.error(`错误：未知命令「${command}」\n`);
+    console.error(USAGE);
+    process.exitCode = 1;
+    return 1;
+}
+process.exitCode = main(process.argv.slice(2));

package/dist/create.js

@@ -0,0 +1,35 @@
+/** create 命令：生成 Agentia 项目脚手架 */
+import { existsSync, mkdirSync, readdirSync, writeFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { mainTs, projectGitignore, projectPackageJson, projectReadme, projectTsconfig, toolIndexTs, emptyRegistryTemplate, } from './templates.js';
+import { registerUnit } from './registry.js';
+function write(dir, rel, content) {
+    const file = join(dir, rel);
+    mkdirSync(join(file, '..'), { recursive: true });
+    writeFileSync(file, content, 'utf8');
+}
+export function createProject(name, parent) {
+    const dir = resolve(parent ?? process.cwd(), name);
+    if (existsSync(dir) && readdirSync(dir).length > 0) {
+        console.error(`错误：目录 ${dir} 已存在且非空`);
+        process.exitCode = 1;
+        return 1;
+    }
+    mkdirSync(dir, { recursive: true });
+    write(dir, 'package.json', projectPackageJson(name));
+    write(dir, 'tsconfig.json', projectTsconfig());
+    write(dir, 'src/main.ts', mainTs(name));
+    write(dir, 'units/hello/index.ts', toolIndexTs('hello'));
+    write(dir, 'units.ts', emptyRegistryTemplate());
+    write(dir, 'README.md', projectReadme(name));
+    write(dir, '.gitignore', projectGitignore());
+    registerUnit(dir, 'hello');
+    console.log(`已创建项目 ${dir}
+
+后续步骤：
+  cd ${dir}
+  npm install
+  export ANTHROPIC_API_KEY=sk-ant-...
+  npm run dev`);
+    return 0;
+}

package/dist/generate.js

@@ -0,0 +1,49 @@
+/** g / generate 命令：在 cwd 生成 units/<name>/ 单元并登记注册表 */
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { promptAssetMd, promptIndexTs, skillIndexTs, subagentIndexTs, subagentSystemMd, toolIndexTs, } from './templates.js';
+import { ensureRegistry, registerUnit } from './registry.js';
+export function generateUnit(type, name) {
+    const cwd = process.cwd();
+    const unitDir = join(cwd, 'units', name);
+    if (existsSync(unitDir)) {
+        console.error(`错误：units/${name}/ 已存在`);
+        process.exitCode = 1;
+        return 1;
+    }
+    mkdirSync(unitDir, { recursive: true });
+    const files = [];
+    const put = (rel, content) => {
+        writeFileSync(join(unitDir, rel), content, 'utf8');
+        files.push(`units/${name}/${rel}`);
+    };
+    switch (type) {
+        case 'tool':
+            put('index.ts', toolIndexTs(name));
+            break;
+        case 'prompt':
+            put('index.ts', promptIndexTs(name));
+            put('asset.md', promptAssetMd(name));
+            break;
+        case 'subagent':
+            put('index.ts', subagentIndexTs(name));
+            put('system.md', subagentSystemMd(name));
+            break;
+        case 'skill':
+            put('index.ts', skillIndexTs(name));
+            break;
+    }
+    ensureRegistry(cwd);
+    const result = registerUnit(cwd, name);
+    console.log(`已生成 ${type} 单元：`);
+    for (const f of files)
+        console.log(`  ${f}`);
+    if (result === 'registered') {
+        console.log(`已登记到 units.ts：{ provide: '${name}' }`);
+    }
+    else {
+        console.log(`units.ts 中「${name}」已注册，跳过登记`);
+    }
+    console.log('提示：discover 目录扫描路线下无需登记即可生效；显式装配路线从 units.ts 引入 providers');
+    return 0;
+}

package/dist/registry.js

@@ -0,0 +1,34 @@
+/** units.ts 注册表 codemod：基于 @agentia 标记行插入/跳过条目，幂等 */
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { IMPORTS_END_MARKER, ENTRIES_END_MARKER, emptyRegistryTemplate, kebabToPascal, } from './templates.js';
+export class RegistryError extends Error {
+}
+/** 注册表文件不存在时按空模板创建 */
+export function ensureRegistry(dir) {
+    const file = join(dir, 'units.ts');
+    if (!existsSync(file)) {
+        writeFileSync(file, emptyRegistryTemplate(), 'utf8');
+    }
+    return file;
+}
+/** 把单元登记进 dir/units.ts；已存在同名条目则跳过。标记行缺失时报错。 */
+export function registerUnit(dir, name) {
+    const file = ensureRegistry(dir);
+    const content = readFileSync(file, 'utf8');
+    const importLine = `import ${kebabToPascal(name)} from './units/${name}/index.js';`;
+    const entryLine = `  { provide: '${name}', useClass: ${kebabToPascal(name)} },`;
+    if (content.includes(`'./units/${name}/index.js'`) || content.includes(`provide: '${name}'`)) {
+        return 'already';
+    }
+    const lines = content.split('\n');
+    const importsEnd = lines.findIndex((l) => l.trim() === IMPORTS_END_MARKER);
+    const entriesEnd = lines.findIndex((l) => l.trim() === ENTRIES_END_MARKER);
+    if (importsEnd === -1 || entriesEnd === -1) {
+        throw new RegistryError(`units.ts 缺少 ${IMPORTS_END_MARKER} / ${ENTRIES_END_MARKER} 标记行，无法自动登记；请手工维护该文件`);
+    }
+    lines.splice(entriesEnd, 0, entryLine);
+    lines.splice(importsEnd, 0, importLine);
+    writeFileSync(file, lines.join('\n'), 'utf8');
+    return 'registered';
+}

package/dist/templates.js

@@ -0,0 +1,227 @@
+/** 命名工具与所有文件模板（零依赖） */
+const NAME_RE = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
+export function isValidName(name) {
+    return NAME_RE.test(name);
+}
+/** hello-world → HelloWorld */
+export function kebabToPascal(name) {
+    return name
+        .split('-')
+        .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+        .join('');
+}
+/** hello-world → hello_world */
+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);
+}
+// ---------- units.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 自动更新，也可手工编辑）
+// @agentia:imports
+${IMPORTS_END_MARKER}
+import type { Provider } from '@migor/agentia';
+
+/** 显式装配路线：createApp({ providers, system: ... })（与 discover 目录扫描二选一或混用） */
+export const providers: Provider[] = [
+  // @agentia:entries
+  ${ENTRIES_END_MARKER}
+];
+`;
+}
+// ---------- create 命令模板 ----------
+export function projectPackageJson(name) {
+    return `${JSON.stringify({
+        name,
+        private: true,
+        type: 'module',
+        scripts: {
+            dev: 'tsx src/main.ts',
+            typecheck: 'tsc --noEmit -p tsconfig.json',
+        },
+        dependencies: { '@migor/agentia': '^0.0.1' },
+        devDependencies: {
+            tsx: '^4.19.0',
+            typescript: '^7.0.2',
+            '@types/node': '^22.0.0',
+        },
+    }, null, 2)}\n`;
+}
+export function projectTsconfig() {
+    return `${JSON.stringify({
+        compilerOptions: {
+            target: 'ES2022',
+            module: 'NodeNext',
+            moduleResolution: 'NodeNext',
+            lib: ['ES2022'],
+            strict: true,
+            esModuleInterop: true,
+            skipLibCheck: true,
+        },
+        include: ['src', 'units.ts'],
+    }, null, 2)}\n`;
+}
+export function mainTs(name) {
+    return `import { createApp, SystemPrompt } from '@migor/agentia';
+
+const app = await createApp({
+  name: '${name}',
+  discover: 'units', // 目录约定：units/<name>/ 一单元一文件夹，启动期扫描装配
+  system: new SystemPrompt().add('role', '你是 ${name} 的主 agent，按任务自主调度菜单里的单元。', true),
+});
+
+const { result } = await app.run(
+  [{ role: 'user', content: process.argv[2] ?? '介绍一下你自己' }],
+);
+console.log(result.finalText);
+`;
+}
+export function projectReadme(name) {
+    return `# ${name}
+
+基于 [Agentia](https://github.com/) 框架的 agent 应用。
+
+## 目录约定
+
+\`units/<name>/\` 一单元一文件夹，每个单元是一个 default export 的类，用装饰器声明能力：
+
+- \`@Tool\` 工具：主 agent 可调用（input → value）
+- \`@Skill\` 技能：方法体内通过 \`ctx.llm()\` 调 LLM
+- \`@SubAgent\` 子代理：按 system 角色设定独立跑一轮
+- \`@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\` 自动维护，也可手工编辑）。
+
+两者二选一或混用。
+
+## 生成单元
+
+\`\`\`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）
+\`\`\`
+
+生成的单元在 \`units/<name>/\`，并自动登记到 \`units.ts\`。
+
+## 运行
+
+需要 Anthropic API key：
+
+\`\`\`bash
+export ANTHROPIC_API_KEY=sk-ant-...
+npm run dev -- "你的问题"
+\`\`\`
+`;
+}
+export function projectGitignore() {
+    return `node_modules
+dist
+`;
+}
+// ---------- g 命令单元模板 ----------
+export function toolIndexTs(name) {
+    const cls = kebabToPascal(name);
+    const method = kebabToSnake(name);
+    return `import { Tool } from '@migor/agentia';
+
+/** ${name} 工具单元 */
+export default class ${cls} {
+  @Tool({
+    description: '示例工具：回显输入',
+    schema: {
+      type: 'object',
+      properties: { text: { type: 'string' } },
+      required: ['text'],
+      additionalProperties: false,
+    },
+    strict: true,
+  })
+  ${method}(input: { text: string }): string {
+    return \`echo: \${input.text}\`;
+  }
+}
+`;
+}
+export function promptIndexTs(name) {
+    const cls = kebabToPascal(name);
+    const method = kebabToSnake(name);
+    return `import { Prompt, asset } from '@migor/agentia';
+
+/** ${name} 文本资产单元 */
+export default class ${cls} {
+  @Prompt({ description: '${name} 文本资产（描述何时该拉取）' })
+  ${method}(): string {
+    return asset(import.meta.url, './asset.md');
+  }
+}
+`;
+}
+export function promptAssetMd(name) {
+    return `# ${name}
+
+在此编写提示文本资产（按需被主 agent 拉取进上下文）。
+`;
+}
+export function subagentIndexTs(name) {
+    const cls = kebabToPascal(name);
+    const method = kebabToSnake(name);
+    return `import { SubAgent, asset } from '@migor/agentia';
+
+/** ${name} 子代理单元 */
+export default class ${cls} {
+  @SubAgent({
+    description: '示例子代理：按 system.md 的角色设定独立处理任务',
+    schema: {
+      type: 'object',
+      properties: { task: { type: 'string' } },
+      required: ['task'],
+      additionalProperties: false,
+    },
+    system: asset(import.meta.url, './system.md'),
+  })
+  // 方法体不会执行：@SubAgent 只读取方法名与装饰器元数据，调用时由框架按 system 另起 agent 执行
+  ${method}(_input: { task: string }): void {}
+}
+`;
+}
+export function subagentSystemMd(name) {
+    return `# ${name}
+
+在此编写子代理的角色描述（作为其子 agent 的 system prompt）。
+`;
+}
+export function skillIndexTs(name) {
+    const cls = kebabToPascal(name);
+    const method = kebabToSnake(name);
+    return `import { Skill } from '@migor/agentia';
+import type { SkillContext } from '@migor/agentia';
+
+/** ${name} 技能单元 */
+export default class ${cls} {
+  @Skill({
+    description: '示例技能：就给定主题调用 LLM 产出要点',
+    schema: {
+      type: 'object',
+      properties: { topic: { type: 'string' } },
+      required: ['topic'],
+      additionalProperties: false,
+    },
+  })
+  async ${method}(input: { topic: string }, ctx: SkillContext): Promise<string> {
+    const r = await ctx.llm({ prompt: \`就「\${input.topic}」给出三个要点\` });
+    return r.text;
+  }
+}
+`;
+}

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@migor/cli",
+  "version": "0.0.1",
+  "description": "Agentia 框架命令行工具：create 脚手架 + g 单元生成器",
+  "type": "module",
+  "bin": {
+    "agentia": "./dist/cli.js"
+  },
+  "files": ["dist"],
+  "repository": "retrychx/agentia",
+  "keywords": ["agentia", "agent", "cli", "scaffold"],
+  "engines": { "node": ">=18" },
+  "publishConfig": { "access": "public" },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.2",
+    "typescript": "^7.0.2"
+  }
+}