@mison/ag-kit-cn 3.0.0-beta.0 → 3.0.0

package/tests/standards-compliance.test.js

@@ -0,0 +1,266 @@
+const { test, describe } = require('node:test');
+const assert = require('node:assert');
+const fs = require('fs');
+const path = require('path');
+
+const REF_ROOT = path.resolve('reference/antigravity-kit');
+const REF_AGENTS_ROOT = path.resolve('reference/antigravity-kit/.agents');
+const REF_LEGACY_AGENT_ROOT = path.resolve('reference/antigravity-kit/.agent');
+const REF_SCRIPTS_ROOT = fs.existsSync(REF_AGENTS_ROOT) ? REF_AGENTS_ROOT : REF_LEGACY_AGENT_ROOT;
+const HAS_REF_SCRIPTS_ROOT = fs.existsSync(REF_SCRIPTS_ROOT);
+
+function collectTokens(content, regex) {
+    const tokens = new Set();
+    for (const match of String(content || "").matchAll(regex)) {
+        tokens.add(match[1] || match[0]);
+    }
+    return tokens;
+}
+
+describe('Standards Compliance', () => {
+    test('all skill directories should include SKILL.md', () => {
+        const skillsRoot = path.resolve('.agents/skills');
+        assert.ok(fs.existsSync(skillsRoot), 'missing .agents/skills');
+
+        const skillDirs = fs
+            .readdirSync(skillsRoot, { withFileTypes: true })
+            .filter((entry) => entry.isDirectory())
+            .map((entry) => path.join(skillsRoot, entry.name));
+
+        for (const dir of skillDirs) {
+            const skillMd = path.join(dir, 'SKILL.md');
+            assert.ok(fs.existsSync(skillMd), `missing SKILL.md in ${path.relative(process.cwd(), dir)}`);
+        }
+    });
+
+    test('deprecated .codex primary-layout wording should be removed from user-facing docs and generator', () => {
+        const targets = [
+            'README.md',
+            'docs/PLAN.md',
+            'docs/TECH.md',
+            'bin/core/generator.js',
+        ];
+        const skipped = [];
+
+        for (const rel of targets) {
+            const abs = path.resolve(rel);
+            if (!fs.existsSync(abs)) {
+                skipped.push(rel);
+                continue;
+            }
+            const content = fs.readFileSync(abs, 'utf8');
+            assert.ok(!content.includes('Managed resources are synchronized under `.codex/`.'), `${rel} still contains deprecated .codex guidance`);
+            assert.ok(!content.includes('Do not edit files under `.codex/` directly.'), `${rel} still contains deprecated .codex guidance`);
+        }
+
+        if (skipped.length > 0) {
+            console.warn(`[standards-compliance] skipped missing optional files: ${skipped.join(', ')}`);
+        }
+    });
+
+    test('critical mechanism tokens should remain aligned with reference snapshot', { skip: !fs.existsSync(REF_ROOT) }, () => {
+        const refRoot = REF_ROOT;
+        const tokenRegex = /(ag-kit|python3?|checklist\.py|verify_all\.py|security_scan\.py|ux_audit\.py|accessibility_checker\.py|schema_validator\.py|lint_runner\.py|type_coverage\.py|playwright_runner\.py|lighthouse_audit\.py|api_validator\.py|mobile_audit\.py|seo_checker\.py|geo_checker\.py|i18n_checker\.py|\.agent\/|\.agents\/|\.agents-backup\/|\.codex\/|AGENTS\.md|antigravity\.rules|manifest\.json|--target|--targets|--fix|--path|--no-index|--dry-run|--quiet|--force)/g;
+        const slashCommandRegex = /(?:^|[\s`"'(\[])(\/(?:brainstorm|create|debug|deploy|enhance|orchestrate|plan|preview|status|test|ui-ux-pro-max))(?=$|[\s`"'，。,.:：)\]])/gm;
+
+        const markdownFiles = [];
+        const stack = [refRoot];
+        while (stack.length > 0) {
+            const current = stack.pop();
+            for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
+                const abs = path.join(current, entry.name);
+                if (entry.isDirectory()) {
+                    stack.push(abs);
+                    continue;
+                }
+                if (/\.(md|mdx|txt)$/i.test(entry.name)) {
+                    markdownFiles.push(abs);
+                }
+            }
+        }
+
+        const mismatches = [];
+        for (const refFile of markdownFiles) {
+            const rel = path.relative(refRoot, refFile);
+            const localFile = path.resolve(rel);
+            if (!fs.existsSync(localFile)) continue;
+
+            const refContent = fs.readFileSync(refFile, 'utf8');
+            const refTokens = new Set([
+                ...collectTokens(refContent, tokenRegex),
+                ...collectTokens(refContent, slashCommandRegex),
+            ]);
+            if (refTokens.size === 0) continue;
+
+            const localContent = fs.readFileSync(localFile, 'utf8');
+            const localTokens = new Set([
+                ...collectTokens(localContent, tokenRegex),
+                ...collectTokens(localContent, slashCommandRegex),
+            ]);
+
+            const missing = [...refTokens].filter((token) => !localTokens.has(token));
+            if (missing.length > 0) {
+                mismatches.push({ rel, missing });
+            }
+        }
+
+        assert.strictEqual(
+            mismatches.length,
+            0,
+            `critical mechanism tokens drifted:\n${mismatches
+                .slice(0, 10)
+                .map((item) => `${item.rel} -> ${item.missing.join(', ')}`)
+                .join('\n')}`,
+        );
+    });
+
+    test('user-facing docs should track current repo and global skill locations', () => {
+        const file = path.resolve('docs/TECH.md');
+        const content = fs.readFileSync(file, 'utf8');
+
+        assert.ok(content.includes('$HOME/.codex/skills/'), 'missing global skill path: $HOME/.codex/skills/');
+        assert.ok(content.includes('$HOME/.gemini/skills/'), 'missing global skill path: $HOME/.gemini/skills/');
+        assert.ok(content.includes('$HOME/.gemini/antigravity/skills/'), 'missing global skill path: $HOME/.gemini/antigravity/skills/');
+        assert.ok(content.includes('.agents/skills'), 'missing repo skill path: .agents/skills');
+        assert.ok(!content.includes('$HOME/.agents/skills/'), 'should not contain deprecated global path: $HOME/.agents/skills/');
+    });
+
+    test('.agents script files should stay identical to reference snapshot', { skip: !HAS_REF_SCRIPTS_ROOT }, () => {
+        const refScriptsRoot = REF_SCRIPTS_ROOT;
+        const mismatches = [];
+
+        const stack = [refScriptsRoot];
+        while (stack.length > 0) {
+            const current = stack.pop();
+            for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
+                const abs = path.join(current, entry.name);
+                if (entry.isDirectory()) {
+                    stack.push(abs);
+                    continue;
+                }
+                if (!abs.includes(`${path.sep}scripts${path.sep}`)) continue;
+                if (abs.includes(`${path.sep}__pycache__${path.sep}`) || abs.endsWith('.pyc')) continue;
+
+                const rel = path.relative(refScriptsRoot, abs);
+                const localFile = path.resolve('.agents', rel);
+                if (!fs.existsSync(localFile)) {
+                    mismatches.push(`${rel} (missing local file)`);
+                    continue;
+                }
+
+                const refContent = fs.readFileSync(abs, 'utf8');
+                const localContent = fs.readFileSync(localFile, 'utf8');
+                if (refContent !== localContent) {
+                    mismatches.push(rel);
+                }
+            }
+        }
+
+        assert.strictEqual(
+            mismatches.length,
+            0,
+            `script content drifted:\n${mismatches.slice(0, 20).join('\n')}`,
+        );
+    });
+
+    test('critical path handling should avoid hardcoded platform separators in managed paths', () => {
+        const adapterFile = path.resolve('bin/adapters/codex.js');
+        const content = fs.readFileSync(adapterFile, 'utf8');
+
+        // Keep this focused on managed path constants that must remain path.join-driven.
+        assert.ok(content.includes('path.join'), 'codex adapter should use path.join for managed paths');
+        assert.ok(content.includes('os.tmpdir()'), 'codex adapter should use os.tmpdir() for temp paths');
+    });
+
+    test('official antigravity docs baselines should be present in localized pages', () => {
+        const checks = [
+            {
+                file: 'web/src/app/docs/skills/page.tsx',
+                required: [
+                    'SKILL.md',
+                    'workspace-root',
+                    '~/.gemini/antigravity/skills',
+                    'description',
+                    'scripts/',
+                    'examples/',
+                    'resources/',
+                    'Discovery',
+                    'Activation',
+                    'Execution',
+                    '--help',
+                ],
+            },
+            {
+                file: 'web/src/app/docs/rules-workflows/page.tsx',
+                required: [
+                    '12,000',
+                    '~/.gemini/GEMINI.md',
+                    '.agent/rules',
+                    'Manual',
+                    'Always On',
+                    'Model Decision',
+                    'Glob',
+                    '@filename',
+                    '/workflow-name',
+                ],
+            },
+            {
+                file: 'web/src/app/docs/task-groups/page.tsx',
+                required: ['规划模式', '总体目标', '已编辑文件', '待处理区'],
+            },
+            {
+                file: 'web/src/app/docs/strict-mode/page.tsx',
+                required: ['Allowlist/Denylist', 'Request Review', '.gitignore', '工作区隔离'],
+            },
+            {
+                file: 'web/src/app/docs/sandbox-mode/page.tsx',
+                required: [
+                    'sandbox-exec',
+                    'Enable Terminal Sandboxing',
+                    'Sandbox Allow Network',
+                    'Bypass Sandbox',
+                    'Strict Mode',
+                ],
+            },
+            {
+                file: 'web/src/app/docs/mcp/page.tsx',
+                required: [
+                    'Model Context Protocol',
+                    'MCP Store',
+                    'Manage MCP Servers',
+                    'View raw config',
+                    'mcp_config.json',
+                ],
+            },
+            {
+                file: 'web/src/app/docs/command/page.tsx',
+                required: ['Command + I', 'Ctrl + I'],
+            },
+            {
+                file: 'web/src/app/docs/allowlist-denylist/page.tsx',
+                required: ['BadUrlsChecker', 'always allow', 'localhost'],
+            },
+            {
+                file: 'web/src/app/docs/browser-subagent/page.tsx',
+                required: ['DOM 捕获', '截图', '蓝色边框'],
+            },
+        ];
+
+        const missing = [];
+        for (const { file, required } of checks) {
+            const abs = path.resolve(file);
+            const content = fs.readFileSync(abs, 'utf8');
+            for (const token of required) {
+                if (!content.includes(token)) {
+                    missing.push(`${file} -> ${token}`);
+                }
+            }
+        }
+
+        assert.strictEqual(
+            missing.length,
+            0,
+            `localized docs missing official baseline tokens:\n${missing.join('\n')}`,
+        );
+    });
+});

package/tests/transformer.test.js

@@ -0,0 +1,74 @@
+const { test, describe, beforeEach, afterEach } = require("node:test");
+const assert = require("node:assert");
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const ResourceTransformer = require("../bin/core/transformer");
+
+describe("ResourceTransformer", () => {
+    let tempDir;
+
+    beforeEach(() => {
+        tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "ag-kit-transformer-test-"));
+    });
+
+    afterEach(() => {
+        fs.rmSync(tempDir, { recursive: true, force: true });
+    });
+
+    function transformWorkflow(markdown) {
+        const workflowPath = path.join(tempDir, "workflow.md");
+        fs.writeFileSync(workflowPath, markdown, "utf8");
+
+        const result = ResourceTransformer.transform({
+            skills: [],
+            workflows: [{ name: "demo", path: workflowPath, type: "workflow" }],
+        });
+
+        return result.mappedFiles.find((item) => item.destPath.endsWith("/SKILL.md"));
+    }
+
+    test("workflow frontmatter should parse CRLF and keep colon in description", () => {
+        const mapped = transformWorkflow([
+            "---\r",
+            "description: \"Run /debug: inspect failures\"\r",
+            "---\r",
+            "",
+            "# Workflow body",
+        ].join("\n"));
+
+        assert.ok(mapped);
+        assert.ok(mapped.content.includes("description: \"Run /debug: inspect failures\""));
+        assert.ok(mapped.content.includes("# Workflow body"));
+    });
+
+    test("workflow frontmatter should parse folded multiline description", () => {
+        const mapped = transformWorkflow([
+            "---",
+            "description: >",
+            "  先执行 /plan",
+            "  再执行 /debug",
+            "---",
+            "",
+            "# Workflow body",
+        ].join("\n"));
+
+        assert.ok(mapped);
+        assert.ok(mapped.content.includes("description: \"先执行 /plan 再执行 /debug\""));
+    });
+
+    test("workflow frontmatter should parse indented multiline description", () => {
+        const mapped = transformWorkflow([
+            "---",
+            "description:",
+            "  统一排查流程: 先收集日志",
+            "  再定位根因",
+            "---",
+            "",
+            "# Workflow body",
+        ].join("\n"));
+
+        assert.ok(mapped);
+        assert.ok(mapped.content.includes("description: \"统一排查流程: 先收集日志 再定位根因\""));
+    });
+});

package/docs/codex-rules-template.md

@@ -1,36 +0,0 @@
-# Codex `.rules` 模板（手动配置）
-
-> 用途：给 Codex 官方规则引擎提供命令审批策略。  
-> 注意：这不是 `antigravity.rules` 的替代品，二者职责不同。
-
-## 路径约定
-
-- 全局默认路径：`~/.codex/rules/default.rules`
-- 本项目不会自动写入该文件，请按需手动创建。
-
-## 最小模板（Starlark）
-
-```python
-# default.rules
-# 允许常见只读命令直接执行，其余命令走人工审批
-
-load("builtin://rules/rules.star", "prefix_rule")
-
-rules = [
-    prefix_rule(["ls"], action="allow"),
-    prefix_rule(["cat"], action="allow"),
-    prefix_rule(["rg"], action="allow"),
-    prefix_rule(["git", "status"], action="allow"),
-]
-```
-
-## 建议策略
-
-1. 先放行只读命令（`ls`/`cat`/`rg`/`git status`）。
-2. 对写操作、网络请求、脚本执行保持 `review` 或 `deny`。
-3. 团队场景下，将策略文件纳入内部安全评审流程。
-
-## 与 `antigravity.rules` 的关系
-
-- `antigravity.rules`：本仓库在工作区注入的托管说明内容，用于记录受管资源与运维约束。
-- `.rules`：Codex 官方可执行审批规则（Starlark），影响命令放行策略。

package/docs/mapping-spec.md

@@ -1,62 +0,0 @@
-# Full 模式资源映射规范
-
-本文描述 v3 统一目录体系下的资源映射。
-
-## 1. Canonical 与 Projection
-
-- Canonical：`.agents/**`
-- Projection：`.agent/**`、`.gemini/**`、根 `AGENTS.md`/`antigravity.rules` 托管区块
-
-## 2. 关键映射规则
-
-### 2.1 Skills
-- Canonical 路径：`.agents/skills/<name>/SKILL.md`
-- Antigravity 兼容：投影到 `.agent/skills/<name>/SKILL.md`
-- Codex 兼容：直接读取 `.agents/skills/*`
-
-### 2.2 Workflows
-- Canonical 路径：`.agents/workflows/<name>.md`
-- Codex 兼容增强：额外生成 `workflow-<name>` 的技能桥接（位于 `.agents/skills/`）
-
-### 2.3 Agents
-- Canonical 路径：`.agents/agents/*.md`
-- Gemini 兼容：写入 `.gemini/agents/ag-kit-*.md`（追加模式，保留用户文件）
-
-### 2.4 MCP
-- Canonical：`.agents/mcp_config.json`
-- Gemini 兼容：合并到 `.gemini/settings.json#mcpServers`
-- Context7：同步 `context7` 与 `context7_backup`
-
-## 3. 托管清单 manifest
-
-`manifest.json`（v3）用于：
-- 受管文件哈希校验
-- 漂移检测
-- 覆盖前冲突备份判定
-
-示例：
-
-```json
-{
-  "version": 3,
-  "target": "full",
-  "kitVersion": "3.0.0-beta.0",
-  "files": {
-    "skills/example/SKILL.md": {
-      "hash": "sha256...",
-      "source": "bundled:full/skills/example/SKILL.md"
-    }
-  }
-}
-```
-
-## 4. Legacy 迁移边界
-
-1. 托管 `.codex`：迁移到 `.agents` 后清理。
-2. 非托管 `.codex`：保留不删。
-3. `.agent`/`.gemini`：用于迁移输入或投影冲突处理，不作为主源。
-
-## 5. 官方规则边界
-
-- `antigravity.rules` 是本项目托管说明文件，不是 Codex 官方 `.rules`。
-- Codex 官方审批规则仍在 `~/.codex/rules/default.rules`（参考 `docs/codex-rules-template.md`）。

package/docs/multi-target-adapter.md

@@ -1,46 +0,0 @@
-# 多目标适配器（v3 Full）
-
-当前版本采用统一 full 架构：`.agents` 为唯一主目录，`.agent` 与 `.gemini` 为兼容投影。
-
-## 架构概览
-
-```mermaid
-graph TD
-    CLI[ag-kit CLI] --> Full[Full Adapter]
-    Full --> Canonical[.agents Canonical]
-    Full --> AgentProj[.agent Projection]
-    Full --> GeminiProj[.gemini Projection]
-    Full --> RootManaged[AGENTS.md / antigravity.rules Managed Block]
-```
-
-## 设计原则
-
-1. 单一事实源：只维护 `.agents`。
-2. 兼容投影：对 Antigravity/Gemini/Codex 做最小兼容输出。
-3. 只处理托管文件：非托管 `.codex`、用户 `.gemini` 自定义文件不被覆盖删除。
-4. 冲突可恢复：覆盖前统一备份到 `.agents-backup/<timestamp>/`。
-
-## 命令语义
-
-```bash
-ag-kit init
-ag-kit update
-ag-kit update-all --targets full
-ag-kit doctor --fix
-```
-
-- `--target gemini|codex` 仍兼容，但归一到 full 流程。
-- `status` 显示 canonical/projection/legacy 状态。
-
-## Legacy 迁移
-
-- 支持读取历史 `.agent`、托管 `.codex`、`.gemini` 并收敛到 `.agents`。
-- 非托管 `.codex` 保留，仅做提示。
-
-## MCP 双通道
-
-`.agents/mcp_config.json` 与 `.gemini/settings.json` 会同步主备 Context7：
-- `context7`（官方）
-- `context7_backup`（备用）
-
-官方不可用时可改走备用。

package/docs/official/README.md

@@ -1,45 +0,0 @@
-# 官方规则文档索引
-
-本目录用于记录 Antigravity、Codex、Gemini CLI 的官方规则约定，作为本仓库的对照基线。
-
-## 记录原则
-
-1. 以官方文档原始地址为准，不编造机制。
-2. 本目录可做中文整理，但不应改变官方规则语义。
-3. 每次核对都写入证据索引（URL、时间、SHA/提交记录）。
-
-## 当前基线
-
-- 规则汇总：`docs/official/rules-baseline.md`
-- 证据索引：`docs/official/sources-index.md`
-- 兼容审查：`docs/official/mechanism-compat-audit-2026-03-04.md`
-- 最近集中核对日期：2026-03-04（UTC）
-
-## 覆盖范围
-
-### Antigravity
-
-- Skills：`https://antigravity.google/assets/docs/agent/skills.md`
-- Rules / Workflows：`https://antigravity.google/assets/docs/agent/rules-workflows.md`
-- Agent Modes / Settings：`https://antigravity.google/assets/docs/agent/agent-modes-settings.md`
-- Strict Mode：`https://antigravity.google/assets/docs/agent/strict-mode.md`
-- Sandboxing：`https://antigravity.google/assets/docs/agent/sandbox-mode.md`
-- MCP：`https://antigravity.google/assets/docs/tools/mcp.md`
-
-### Codex
-
-- Skills：`https://developers.openai.com/codex/skills.md`
-- Rules：`https://developers.openai.com/codex/rules.md`
-- AGENTS.md：`https://developers.openai.com/codex/guides/agents-md.md`
-- MCP：`https://developers.openai.com/codex/mcp.md`
-- Workflows：`https://developers.openai.com/codex/workflows.md`
-- Security：`https://developers.openai.com/codex/security.md`
-
-### Gemini CLI
-
-- Skills：`https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/skills.md`
-- Gemini.md：`https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/gemini-md.md`
-- Plan Mode：`https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/plan-mode.md`
-- Subagents：`https://github.com/google-gemini/gemini-cli/blob/main/docs/core/subagents.md`
-- MCP Server：`https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/mcp-server.md`
-- Policy Engine（规则引擎）：`https://github.com/google-gemini/gemini-cli/blob/main/docs/reference/policy-engine.md`

package/docs/official/antigravity/agent-modes-settings.md

@@ -1,64 +0,0 @@
----
-slug: agent-modes-settings
-section: 代理
-title: Agent 模式与设置
-path:
-  - 代理
-  - 模式与设置
----
-
-# Agent 模式与设置（中文整理）
-
-> 来源：`https://antigravity.google/docs/agent-modes-settings`  
-> 同步日期：2026-02-12  
-> 说明：本文件为官方内容的中文整理版，采用标准 Markdown 语法。
-
-## 会话级模式
-
-开始新的 Agent 会话时，用户可以选择不同模式：
-
-- `Planning`：先规划后执行，适合深度研究、复杂任务、协作任务。该模式下，Agent 会使用任务分组、产出 Artifacts，并在执行前进行更充分的分析与规划。
-- `Fast`：直接执行，适合简单且局部的任务，例如重命名变量、执行少量命令等，强调速度。
-
-## 全局设置
-
-全局设置位于设置面板的 `Agent` 标签页，影响所有会话。重点配置如下。
-
-### Artifact 审阅策略
-
-可选项：
-
-- `Always Proceed`：Agent 不等待人工审阅，继续执行。
-- `Request Review`：Agent 在请求审阅后停止，等待用户确认和补充意见。
-
-适用建议：
-
-- 需要严格把关实施计划时，使用 `Request Review`。
-- 追求流程速度且信任当前指令时，使用 `Always Proceed`。
-
-### 终端命令自动执行
-
-针对终端命令生成工具：
-
-- `Request Review`：默认不自动执行命令（允许名单中的命令可自动执行）。
-- `Always Proceed`：默认自动执行命令（拒绝名单中的命令例外）。
-
-补充规则：
-
-- 允许名单（Allow list）和拒绝名单（Deny list）可在 `Agent` 设置中配置。
-- 设置变更仅对后续新消息生效，不影响当前正在进行的回复。
-- 在 Unix shell 中，规则按“命令 token 前缀匹配”。
-- 在 PowerShell 中，规则可匹配命令 token 的任意连续子序列。
-
-### 非工作区文件访问
-
-该选项控制 Agent 是否可访问和编辑当前工作区之外的文件。
-
-默认情况下，Agent 仅能访问：
-
-- 当前工作区文件
-- 应用根目录 `~/.antigravity/` 下的 Antigravity 相关数据（如 Artifacts、Knowledge Items）
-
-风险提示：
-
-- 开启该能力可能暴露本地敏感信息或密钥，请谨慎使用。