bladeacer/lccst

# LCCST (Locust)  一个算法级的工作区守门员，它能将复杂的代码库变更 分解为隔离的、经测试验证的原子级 Git 提交，同时严格 维护架构的凝聚力和 SOLID 不变量。 Locust 作为代码库健康、测试覆盖率和结构性边界的 确定性、零妥协守护者运行——专为将您的 偏好放在首位而构建。 1. **发现与格式化：** 通过严格的工具阶梯运行 lint 和编译器。 2. **代码块聚类：** 将工作区差异分组为隔离的、原子级的单元。 3. **针对性测试：** 验证变更并强制执行严格的、感知生态系统的 覆盖边界。 4. **原子提交生成：** 发布干净的 Conventional Commits 及详细的 测试指标。 ## 运行时模式 Locust 根据您的环境在两种模式下运行： ### 裸 Skill 模式 协议规范 (`SKILL.md`) 直接加载到 LLM 的 上下文窗口中。模型手动遵循规则——检测语言、 运行命令并提交更改。不需要 MCP 服务器。 ### MCP 服务器模式（参考：`src/swarm/`） 位于 `src/index.ts`（构建至 `dist/index.js`）的 MCP 服务器通过工具和提示暴露了完整的 协议——所有逻辑都包含在一个 独立的可分发文件中。AI 代理可以以编程方式调用 `/init`、`/audit` 和 `/swarm` 工具。 有关更多详细信息，请参阅 [src/swarm/README.md](src/swarm/README.md)。 ``` # Go 示例 /init -> Detects go.mod -> swarm runs `go test ./...` # Rust 示例 /init -> Detects Cargo.toml -> swarm runs `cargo test` # Python 示例 /init -> Detects pyproject.toml -> swarm runs `uv run pytest` # Node.js 示例 /init -> Detects package.json -> swarm runs `pnpm test` # Julia 示例 /init -> Detects Project.toml -> swarm runs `julia --project=. -e "using Pkg; Pkg.test()"` # CMake 示例 /init -> Detects CMakeLists.txt -> swarm runs `cmake --build .` ``` ## 操作角色：虚拟员工与发布工程师 在您的工作区生态系统中，Locust 充当混合型 **Staff Architect** 和高度警惕的 **Release Engineer**。它不仅促进更改； 它确保每一次修改都符合长期的工程健康。就像 一位严于律己的同行，它积极防止反模式的创建， 自动化版本控制开销，并拒绝暂存或提交低于 严格质量阈值的代码。 ## 生态系统定位：质量的制衡 虽然现代 AI 工程领域充斥着大量严格专注于 压缩和降低成本的工具，但 Locust 提供了缺失的 理念平衡。它的构建是为了独立运行或与 token 裁剪器并行使用。 | 工具层 | 重点 | 战术机制 | |---|---|---| | **[Ponytail](https://github.com/DietrichGebert/ponytail)** | 代码最小化 | 防止代理样板代码膨胀。 | | **[Headroom](https://github.com/chopratejas/headroom)** | 历史缩减 | 修剪上下文日志和聊天数据。 | | **[Caveman](https://github.com/JuliusBrussee/caveman)** | 输出压缩 | 剥离语法 token 开销。 | | **Locust (LCCST)** | **有效载荷完整性** | **强制执行类型检查、lint 和测试。** | ### Token 投资理念 项目名称本身体现了这种二元性：**LCCST** 是对 **Low Cost**（低成本）资产管理的一个直接双关语，同时对您的 工作区树执行算法级的 **Locality Clustering**（局部聚类）。 像 Ponytail 这样的工具可以阻止 AI 编写*过多*的代码，但它们无法 阻止它破坏您的架构边界。Locust 将 token 视为 战略资本。它将 token 投入到多步验证循环（ 工具阶梯）中，以消除调试损坏的生产构建、理顺混乱的 Git 历史或修复 静默的运行时类型故障所产生的指数级增长的更高下游成本。 ## 核心理念 * **用户偏好优先：** 在定义应用程序载荷时，您明确的首选设计模式和 目标逻辑始终具有优先权。然而， 流水线的核心安全门——包括原子代码块隔离、 工具阶梯和严格的测试通过验证——是不可协商的工作区 不变量，旨在防止结构退化。 * **简化的初始化：** 在启动时使用 `/init` 命令开启 即时、自动化的代码库扫描，帮助您在任何更改开始之前 审计存储库健康状况并发现架构文档缺口。 * **交互式参与循环：** 没有突然的死胡同。系统保持 持续的、协作性的对话——提示您进行确认、暂存 批准或澄清实施路径。 * **主动的语义发现与测试：** 利用 Language Server Protocol (LSP) 数据、Tree-sitter AST 查询和原生测试框架 以动态追踪下游副作用。 * **生态系统原生架构：** 强制执行严格的类型安全边界、 现代项目布局编排器和单一职责接口 （同时动态允许像统一的 HTTP 处理程序这样的内聚性多方法结构）。 * **防御性工程与合规性：** 强制要求在整个 入口点设定验证边界，过滤 token 开销，审计软件包许可证，并 使用 SemVer 规则自动适应单体和模块化/版本化变更日志 布局。 * **质量重于速度：** 优先考虑结构完整性和完整的测试 验证，而不是纯粹的执行速度。版本 3.0.0 强制执行严格的 Mode Gating： 它在被动的 `/audit` 扫描期间保持超精简的 token 占用，仅将 繁重的 completion token 投入保留给完全 证明验证开销合理的执行循环。 * **粒度重于便利性：** 拒绝将多领域 修复捆绑到单个执行块中的诱惑。Locust 应用严格的 **Locality Clustering**（局部聚类），按功能域边界对工作区差异进行分组。 创建多个原子提交的开销是刻意为之， 以保证简便的代码回滚和清晰的存储库历史。 ## 实验场与基准测试 请参阅 [`playground/README.md`](playground/README.md) 了解基准测试套件， 该套件用于衡量在三个参考项目（Python HTTP server、React timer、Go login CRUD）中，skill 引导与普通代码生成之间的 token 影响。 ### 验证矩阵与基线基准测试 下面捕获的基线指标使用了我们的自动化评估 测试工具。数据突出了在非引导生成和结构化协议合规性之间观察到的具体性能差异。 跟踪两个截然不同的 token 指标： * **FCT (File-Content Tokens)：** 最终源文件的静态 token 占用 （运行后通过 `tiktoken` 测量）。 * **ART (Agent Runtime Tokens)：** agent 循环期间消耗的累积 prompt + completion token （通过 `track_runtime.py` 代理捕获）。 分数使用特定领域的评估配置完全标准化为 100 分制。每个子项目根据与其 架构领域相关的特性进行评分（例如，UI 组件不会因为 缺少加密模式而被扣分）。 #### opencode-deepseek-v4-flash-free: skill version v2.8.0 | Agent Runtime | LLM Engine | Skill Layer | Context Tools (MCP) | Subproject | Plain Score | Skill-Guided | Test Status | FCT (Plain) | FCT (Guided) | ART (Plain) | ART (Guided) | | :--- | :--- | :--- | :--- | :--- | :---: | :---: | :---: | :---: | :---: | :---: | :---: | | **opencode** | `deepseek-v4-flash-free` | `v2.8.0` | `lccst-telemetry` | **python-http-server** | 48/100 | **100/100** | PASSED | 655 | 2,229 | 2,639 | 8,984 | | **opencode** | `deepseek-v4-flash-free` | `v2.8.0` | `lccst-telemetry` | **react-timer** | 22/100 | **100/100** | PASSED | 508 | 770 | 2,046 | 3,102 | | **opencode** | `deepseek-v4-flash-free` | `v2.8.0` | `lccst-telemetry` | **go-login-crud** | 49/100 | **100/100** | PASSED | 1,191 | 5,079 | 4,800 | 20,479 | | **Summary** | | | | **Workspace Totals / Avg** | **40/100** | **100/100** | **3/3 Passed** | **2,354** | **8,078** | **9,485** | **32,565** | #### opencode-mimo-v2.5-free: skill version v2.8.0 | Agent Runtime | LLM Engine | Skill Layer | Context Tools (MCP) | Subproject | Plain Score | Skill-Guided | Test Status | FCT (Plain) | FCT (Guided) | ART (Plain) | ART (Guided) | | :--- | :--- | :--- | :--- | :--- | :---: | :---: | :---: | :---: | :---: | :---: | :---: | | **opencode** | `mimo-v2.5-free` | `v2.8.0` | `lccst-telemetry` | **python-http-server** | 32/100 | **100/100** | PASSED | 1,621 | 2,684 | 5,207 | 8,622 | | **opencode** | `mimo-v2.5-free` | `v2.8.0` | `lccst-telemetry` | **react-timer** | 22/100 | **100/100** | PASSED | 735 | 1,506 | 2,360 | 4,837 | | **opencode** | `mimo-v2.5-free` | `v2.8.0` | `lccst-telemetry` | **go-login-crud** | 49/100 | **100/100** | PASSED | 2,452 | 5,756 | 7,877 | 18,497 | | **Summary** | | | | **Workspace Totals / Avg** | **34/100** | **100/100** | **3/3 Passed** | **4,808** | **9,946** | **15,444** | **31,956** | #### opencode-big-pickle: skill version v2.8.0 | Agent Runtime | LLM Engine | Skill Layer | Context Tools (MCP) | Subproject | Plain Score | Skill-Guided | Test Status | FCT (Plain) | FCT (Guided) | ART (Plain) | ART (Guided) | | :--- | :--- | :--- | :--- | :--- | :---: | :---: | :---: | :---: | :---: | :---: | :---: | | **opencode** | `big-pickle` | `v2.8.0` | `lccst-telemetry` | **python-http-server** | 32/100 | **84/100** | PASSED | 610 | 2,210 | 3,575 | 12,952 | | **opencode** | `big-pickle` | `v2.8.0` | `lccst-telemetry` | **react-timer** | 22/100 | **100/100** | PASSED | 384 | 685 | 2,250 | 4,014 | | **opencode** | `big-pickle` | `v2.8.0` | `lccst-telemetry` | **go-login-crud** | 49/100 | **100/100** | PASSED | 823 | 4,621 | 4,823 | 27,086 | | **Summary** | | | | **Workspace Totals / Avg** | **34/100** | **95/100** | **3/3 Passed** | **1,817** | **7,516** | **10,648** | **44,052** | | 指标 | deepseek-v4-flash-free | mimo-v2.5-free | big-pickle | |---|---|---|---|---| | Plain score | 40/100 | 34/100 | 34/100 | | Guided score | 100/100 | 100/100 | 95/100 | | Plain FCT | 2,354 | 4,808 | 1,817 | | Guided FCT | 8,078 | 9,946 | 7,516 | | FCT 开销 | +243% | +107% | +314% | | Plain ART | 9,485 | 15,444 | 10,648 | | Guided ART | 32,565 | 31,956 | 44,052 | | ART 开销 | +243% | +107% | +314% | | 测试通过数 | 3/3 | 3/3 | 3/3 | mimo-v2.5-free 似乎是 token效率最高的，开销为 +107%，但这具有误导性——与 deepseek（40/100，2,354/9,485）相比，其普通得分 (34/100) 伴随着虚高的 FCT (4,808) 和 ART (15,444)，这表明它在普通实现中遇到了困难，需要更多的 token 来生成更差的代码。skill 引导为所有三个项目都提供了 100/100 的得分，但开销百分比看起来人为偏低，因为普通基线已经因为挣扎而非效率被抬高了。deepseek-v4-flash-free 拥有最强的普通基线，并以 +243% 的开销达到了 100/100，这代表了真正的质量投资，而不是从失败中恢复。big-pickle 是唯一一个低于 100/100（95/100，其中 python-http-server 为 84/100）的模型，并产生了最高的开销 (+314%)。go-login-crud 是所有运行器中最繁重的子项目。 ### 核心架构洞察 * **Token 权衡 (FCT)：** skill 引导协议引入了 刻意的文件内容 token 开销（参见上面的 FCT 列），以资助 显式类型定义、稳健的错误处理和强制性单元测试。 * **Agent Runtime Tokens (ART)：** 测试工具跟踪跨 skill 引导开发周期的运行时投资。最繁重的子项目（在上面的 表格中注明）通常占引导 ART 的最大份额， 在受控的计划到执行转换期间隔离结构性错误。 ### 为其他模型添加基准测试 随时克隆存储库并将您的特定于代理的指标 贡献到主矩阵中。有关 更多详细信息，请参阅 [playground README](./playground/README.md)。 欢迎做出贡献，特别是对于前沿模型和如 Claude、GPT、Gemma 4 和 GLM 5.2 这样的本地重量级模型。 ## 安装说明 ### 选项 A：Model Context Protocol (MCP) 服务器设置 要仅克隆最新的提交状态并节省设置开销，请使用浅 克隆： ``` git clone --depth 1 https://github.com/bladeacer/lccst cd lccst ``` 对于支持自动化标准输入/输出 (stdio) 通信守护进程的 AI 运行器 （例如 Claude Code、Cursor、Cline、Windsurf、Codex、Pi、OpenCode、Gemini CLI / Antigravity）。 将以下配置对象添加到您的全局或项目级 MCP 服务器连接数组中（例如 `claude_desktop_config.json`）： ``` { "mcpServers": { "lccst": { "command": "node", "args": ["/absolute/path/to/lccst/dist/index.js"] } } } ``` *注册后，通过您的代理界面调用 `swarm` 提示。* MCP 服务器公开了三个用于编程的工具： - **`init`** -- 映射项目约定并验证环境 - **`audit`** -- 扫描工作区差异并生成提交计划 - **`swarm`** -- 执行完整的发现-聚类-测试-提交循环 ### OpenCode 设置 OpenCode 在项目根目录使用 `opencode.jsonc` 文件进行 MCP 服务器 配置和 skill 注册。 #### 注册主 LCCST MCP 服务器 将以下内容添加到您的 `opencode.jsonc`： ``` { "$schema": "https://opencode.ai/config.json", "mcp": { "lccst": { "type": "local", "command": ["node", "/absolute/path/to/lccst/dist/index.js"], "enabled": true } } } ``` #### 作为 Skill 引用 `SKILL.md` 文件是一个 [Agent Skill](https://agentskills.io/specification)。 OpenCode 会自动发现项目根目录下名为 `SKILL.md` 的 skill。 要在对话中调用 Locust，请使用 `/lccst` 命令或在 您的提示中引用 `@SKILL.md`。 #### 可用的测试脚本 ``` pnpm run build # Compile TypeScript -> dist/index.js pnpm run test # Run all tests (22 unit + 6 integration) pnpm run test:swarm # Swarm library unit tests only pnpm run test:mcp # MCP server integration tests only pnpm run bump 3.0.1 # Bump version across all files ``` ### 选项 B：零设置声明式提取 对于指令驱动的工作流、直接的 CLI 执行，或不需要 后台进程的平台。 #### Claude Code CLI 通过运行时文件引用直接注入规范： ``` claude "Review the active git diff using the parameters in ./SKILL.md" ``` #### GitHub Copilot & OpenCode Agents 根据您的宿主界面，使用 `@` 或 `#` 快捷键在您的会话提示上下文中引用或固定该文件： * 将 `#SKILL.md` 或 `@SKILL.md` 附加到您的聊天输入界面中。 * 目标执行提示：`"在此文件中定义的协议循环上执行我未提交的工作区更改。"` #### Codex & 独立的 Agent Harnesses 将原始文本内容通过管道传递给初始化运行，或通过自定义 扩展层提供： ``` cat SKILL.md | your-agent-runner "Apply this system execution skill" ``` #### 项目级工作区绑定（自动规则锁定） 要永久地将 AI 代理绑定到 Locust 框架约束而不 键入手动提示触发器，请使用适当的目标文件将 `SKILL.md` 直接保存或符号链接到您的 存储库根目录中： * **Cursor IDE：** 在项目根目录中将文件另存为 `.cursorrules`。 * **Cline / VS Code AI Agents：** 在项目 根目录中将文件另存为 `.clinerules`。 * **GitHub Copilot (Editor)：** 将文件另存为 `.github/copilot-instructions.md`。 #### 全局编辑器配置 要将这些规则全局应用于您机器上的所有打开的开发空间，请复制 `SKILL.md` 的原始内容并将其粘贴到您编辑器的 全局行为配置字段中： * **Cursor：** 导航到 `Settings -> Features -> Rules for AI` 并附加 规则集。 * **Windsurf：** 导航到 `Settings -> Memories`，使用 SKILL.md 内容创建或编辑 全局规则条目。 * **VS Code (Cline / Continue)：** 使用规则集内容创建或编辑 `~/.vscode/globalRules.json`，或直接粘贴到扩展程序的全局 配置面板中。 * **JetBrains (AI Assistant)：** 导航到 `Settings -> Tools -> AI Assistant -> Custom Prompts`，并将规则集添加为项目级或全局 指令。 * **GitHub Copilot (CLI)：** 设置 `GITHUB_COPILOT_INSTRUCTIONS` 环境 变量以指向 `SKILL.md` 的本地副本，或将内容附加到 `~/.github/copilot-instructions.md`。 ### 选项 C：通用包注册表集成 对于原生实现去中心化 **Agent Skills Standard**（例如 Claude Code、Cursor、 Windsurf、Roo Code、Gemini CLI、Codex）的平台和命令行界面。这会使用全局 skills 基础设施将根级 `SKILL.md` 文件布局直接注册到您的环境中。 直接从公共 GitHub 源路径安装 skill 块： ``` npx skills add bladeacer/lccst ``` #### 执行工作区模块 通过通用包引擎映射后，通过您的终端运行器配置文件或活动的代理界面顺畅地调用系统 执行流水线： ``` /lccst ``` ## 开发说明 ### 开发者依赖项 | 工具 | 版本 | 用途 | |------|---------|---------| | pnpm | >= 9 | 包管理器（引擎 + 实验场 Node 项目） | | TypeScript | >= 5.4 | 编译引擎源代码 | 基准测试有自己的一组依赖项，详情请参见 [playground README](/playground/README.md)。 ## LLM 使用披露 这是一个 AI skill，在制作该项目时使用了 AI 辅助。 架构、设计决策以及确保代码按预期工作是由 人类完成的。 ## 致谢 Locust 深受 [ponytail](https://github.com/DietrichGebert/ponytail) 的启发。 徽标和海报使用了 [the Iceberg Dark colour scheme by cocopon](https://cocopon.github.io/iceberg.vim/)。 排版使用了 [IBM Plex Mono](https://github.com/IBM/plex) 字体。 [Agent Skills 规范](https://agentskills.io/specification)。 ## 许可证 本项目是开源项目，并根据 MIT License 的条款获得许可。

标签：AI辅助编程, C2, Git工作流, MCP, SOC Prime, 开发工具, 开源框架, 持续集成, 网络安全研究