KazuCocoa/renma

# Renma Renma 是一个用于 Agent 可消费仓库知识的确定性治理与健康度层。 它帮助团队保持技能和共享上下文资产的可见性、可审查性，并确保它们对 Agent runtime 复用是安全的。Renma 不会让关键知识被复制到多个 prompt 中，也不会让其埋没在零散的 Markdown 文件里，而是将这些知识视为一种软件资产：命名、归属、版本化、关联、在 CI 中进行检查，并通过确定性诊断和扫描结果进行审查。 Renma 现在支持 `scan`、`catalog`、`ownership`、`graph`、聚焦图谱视图、`readiness`、重复上下文诊断、语义 diff、`ci-report`、`inspect`、`scaffold`、`suggest-semantic-split` 以及安全诊断 v1。 当仓库包含面向 Agent 的内容时，Renma 尤其有用，例如： - Codex、Claude、Cursor 或其他 Agent 技能 - `AGENTS.md` 和仓库说明 - 共享的产品、领域、QA、平台或工具指南 - 团队拥有的、其生命周期应长于单个 prompt 的上下文资产 - Agent 应该能够引用或检查的参考资料和示例 Renma 不是 Markdown linter，不是 prompt 管理系统，也不是 Agent runtime。Markdown 是当今的存储格式；而产品则是围绕 Agent 可消费仓库知识构建的目录、依赖图谱、所有权模型和就绪度检查。 当你需要回答以下仓库级别的问题时，请使用 Renma： - 这个仓库中存在哪些 Agent 可消费的知识？ - 哪些技能、上下文资产、示例和工具笔记是可复用的？ - 哪些资产没有归属、过期、孤立、不完整、被弃用或已损坏？ - 哪些产品决策、Bug 历史、测试策略或平台指南应该从一次性的 prompt 文本提升为共享上下文？ - 在这次 pull request 期间，面向 Agent 的知识目录发生了什么变化？ ## 分层模型 ``` Tools Codex, Claude, Cursor, CI, editors, internal CLIs Skills agent-facing entrypoints that route an agent toward a task Context Assets Shared domain, product, testing, platform, and tool knowledge Catalog Deterministic IDs, ownership, lifecycle state, dependencies, evidence Repository Git-reviewed source of truth for agent-consumable knowledge ``` 工具在 runtime 决定要做什么。技能告诉 Agent 何时以及如何使用某项功能。上下文资产持有可复用的知识。Renma 对底层进行编目和验证，以便工具和 Agent 无需从过期、孤立、重复或无归属的文件中盲目猜测。 ## 为什么选择 Renma？ 随着 AI Agent 仓库的增长，专业知识通常会在技能和 prompt 中被重复复制。测试启发式方法、领域风险、工具使用笔记、产品决策和团队特定契约会逐渐产生分歧。所有权变得不明确。引用失效。被弃用的指导仍然可以访问。新工程师和 Agent 无法分辨哪些知识是权威的。 Renma 赋予这些材料与团队期望从源代码中获得相同的运营姿态： - 跨技能和 Agent 复用 - 由团队或维护者拥有 - 可在 pull request 中审查 - 在 Git 中进行版本控制 - 通过显式引用和依赖关系组合 - 通过确定性检查进行验证 - 易于在本地和 CI 中检查 例如，测试组织可以将边界值分析、负面测试、回归风险、支付幂等性、重复收费预防、退款边缘情况、移动端离线行为、移动端自动化笔记以及已知的团队特定风险保留为共享上下文资产，而不是将它们埋没在各个单独的技能中。 ## 仓库结构 Renma 支持现有的技能本地引用、profiles 和示例。首选模型是将可复用的知识作为一等公民置于 `contexts/` 下： ``` skills/ testing/ test-case-generation.skill.md spec-review.skill.md regression-planning.skill.md contexts/ testing/ boundary-value-analysis.md negative-testing.md regression-risk.md domain/ payment/ idempotency.md duplicate-charge.md refund-risk.md mobile/ offline-behavior.md background-resume.md tools/ appium/ usage-guideline.md limitations.md teams/ checkout/ payment-api-contracts.md known-risk-patterns.md ``` 推荐使用 `contexts/`。为了兼容性，也会扫描 `context/`。这两个根目录下的文件将被编目为一等公民 `context` 资产，而技能本地的 `references/` 仍作为 `reference` 资产受到支持。 ## Renma 目前能做什么 Renma 是一个低依赖的 TypeScript CLI，它扫描本地仓库并构建 Agent 可消费资产的确定性目录。 目前它会扫描： - AI Agent 技能 - 仓库说明，例如 `AGENTS.md` - `context/` 和 `contexts/` 下的共享上下文 Markdown - 技能 profiles、引用和示例 - 工具指南和支持文件 - README 级别的仓库文档 它会生成： - 文件和行级别的诊断 - 具有确定性资产 ID 的目录报告 - 所有权覆盖率报告 - 依赖图谱报告 - Agent 就绪度报告 - 用于 CI 和下游工具的 JSON 输出 - 专为人类或 Agent 设计的、可转化为可执行修复 prompt 的文本输出 诊断结果的目的是解释哪里出了问题、为什么重要、证据在哪里、在修复时需要保留什么，以及如何验证修复结果。Renma 本身不会应用大规模的语义重写；它会输出结构化的诊断结果，以便人类或编程 Agent 可以提出可审查的 patch 并再次运行 Renma。 ### 重复上下文诊断 `renma scan` 会报告跨已发现技能、Agent、profiles、引用、示例和共享上下文资产的确定性重复上下文候选项。这些发现是进行合并的证据，而不是自动化的真相裁决： ``` LLM proposes. Renma verifies. Human approves. ``` MVP 规则 ID 包括： - `MAINT-REPEATED-SECTION`：用于重复的规范化章节哈希值。 - `MAINT-REPEATED-HEADING`：用于重复的非通用标题。 - `MAINT-REPEATED-CODE-BLOCK`：用于重复的实质性代码块。 - `MAINT-REPEATED-LINK`：用于重复的仓库上下文链接目标。 - `MAINT-REPEATED-CONTEXT-PATTERN`：用于重复的 token shingles。 Renma 会对空白字符进行规范化处理，并且仅报告具有稳定解析器证据的跨文件候选项。修复提示文本要求维护者在合并已拥有的知识时，保留所有权边界、程序性细节和人工批准环节。 ## Renma 与相邻工具的区别 Prompt 管理和评估工具侧重于 prompt、trace 和模型输出。 Renma 的关注点低一层：即 prompt、Agent 和工具所依赖的可复用上下文资产和技能。 知识管理工具帮助人类组织笔记和文档。 Renma 专注于机器可消费的仓库知识，这些知识可以在 AI 工作流中被拥有、引用、验证和重用。 软件目录追踪服务、库、所有权和生命周期。 Renma 将类似的目录模型应用于上下文资产。 ## 首次使用 在当前仓库中尝试 Renma： ``` npx renma scan . npx renma catalog . --format json npx renma graph . --format mermaid npx renma readiness . npx renma diff . --from main --to HEAD --format markdown ``` 第一个命令不需要你预先设计知识架构。它会扫描仓库，构建本地目录，并报告明显的健康问题，如失效的链接、不明确的所有权、有风险的指令、薄弱的结构以及 Agent 可能难以信任的上下文。 如果你正在从源代码开发 Renma： ``` npm install npm run build node dist/index.js scan . ``` 然后检查目录和图谱： ``` node dist/index.js catalog . --format json node dist/index.js graph . --format mermaid node dist/index.js readiness . node dist/index.js diff . --from main --to HEAD --format markdown ``` 使用 `scaffold` 编写技能或上下文资产： ``` npx renma scaffold skill skills/testing/spec-review/SKILL.md --id skill.testing.spec-review --title "Spec Review" --owner qa-platform --tags testing,spec-review npx renma scaffold context contexts/testing/boundary-value-analysis.md --id context.testing.boundary-value-analysis --title "Boundary Value Analysis" --owner qa-platform --tags testing ``` 检查新技能的聚焦图谱： ``` npx renma graph . --focus skill.testing.spec-review --format mermaid npx renma inspect skills/testing/spec-review/SKILL.md ``` 聚焦图谱视图是检查工具；它们不会为 Agent 选择、注入或加载 runtime 上下文。 `scaffold --format prompt` 会为 `` 输出一个适配 Codex/Claude 的编写 prompt，且不写入任何文件。`scaffold --format json` 会输出结构化的 scaffold 数据。 语义 diff 会比较跨 Git ref 的确定性目录、图谱、就绪度和诊断快照。 它不会解释任意散文的语义、组装 prompt、选择上下文、调用 LLM、修复文件或检出/更改工作树。 一个实用的初始流程是： 1. 运行 `scan` 查找失效的链接、薄弱的结构、有风险的指令、缺失的生命周期元数据以及其他可修复的问题。 2. 运行 `catalog` 查看 Renma 发现了哪些技能、上下文资产、引用、示例和支持文件。 3. 运行 `ownership` 查找没有明确归属的资产。 4. 运行 `graph` 检查依赖关系并发现孤立或过度耦合的知识。 5. 运行 `readiness` 总结仓库是否足够健康以供 Agent 使用。 此循环不需要 LLM。其核心分析是确定性的，因此相同的仓库状态会在本地开发、CI 和代码审查中产生稳定的证据。 ## CLI 命令 ``` renma scan renma catalog renma ownership renma graph renma readiness renma diff --from --to renma ci-report --from --to renma inspect renma inspect --lines L10-L42 renma suggest-semantic-split ``` 常见示例： ``` renma scan . renma scan . --format json renma scan . --fail-on high renma catalog . --format json renma ownership . --include-owned renma graph . --format mermaid renma graph . --focus skill.testing.spec-review --view full renma readiness . renma diff . --from main --to HEAD --format markdown renma ci-report . --from main --to HEAD --format markdown renma inspect contexts/testing/boundary-value-analysis.md ``` 当 Renma 是 CI 或其他工具的一部分时，请使用 JSON 输出。使用 markdown 输出作为 PR 审查产物。当人类或编程 Agent 需要简洁的修复列表时，请使用文本输出。 `ci-report` 退出行为： - PASS/WARN：退出代码 0 - FAIL：退出代码 1 - 命令、runtime 或配置错误：退出代码 2 ## 扫描范围 默认情况下，Renma 会查找： ``` skills/**/SKILL.md .agents/**/*.md AGENTS.md README.md context/**/*.md contexts/**/*.md skills/**/profiles/**/*.md skills/**/references/**/*.md skills/**/examples/**/*.md skills/**/scripts/**/* tools/**/* ``` Renma 也能理解技能本地的支持目录，例如 `profiles/`、`references/` 和 `examples/`。在技能之间共享的可重用知识通常应该移动到 `contexts/` 中，这样它就可以拥有自己的所有者、生命周期、依赖项和审查历史记录。 ## 配置 在仓库根目录添加 `renma.config.json` 以调整发现和 CI 行为： ``` { "fail_on": "high", "format": "json", "globs": [ "skills/**/SKILL.md", "AGENTS.md", "contexts/**/*.md" ], "exclude": [ "node_modules", "dist", ".git" ], "max_file_size_bytes": 524288, "max_depth": 16, "concurrency": 16, "layout": { "workflow_aliases": {} } } ``` ## 资产元数据 当可复用的资产在前置元数据中声明轻量级元数据时，Renma 的效果最佳： ``` --- id: context.testing.boundary-value-analysis owner: qa-platform status: stable requires_context: - context.testing.negative-testing --- # 边界值分析 ``` 有用的元数据包括： - `id`：稳定的目录 ID - `title`：人类可读的资产标题 - `owner`：负责该资产的团队、个人或组 - `status`：生命周期状态，例如 `experimental`、`stable`、`deprecated` 或 `archived` - `version`：当仓库使用显式版本控制时的资产版本 - `tags`：搜索和分组标签 - `requires_context`：此资产通常依赖的上下文资产 - `optional_context`：仅在特定情况下有用的上下文资产 - `conflicts`：不应一起应用的上下文资产 - `superseded_by`：当此资产被弃用时的替代资产 Renma 可以从路径和标题推断出一些信息，但显式元数据会使所有权和依赖关系报告更具价值。 Renma 从技能和上下文资产中读取确定性的前置元数据。部分元数据字段支持 YAML 风格的块列表，这使得编写的元数据保持显式且可审查： ``` --- id: context.testing.boundary-value-analysis-v2 title: Boundary Value Analysis owner: qa-platform status: stable version: 1.0.0 tags: - testing - spec-review when_to_use: - Designing tests around numeric, date, quantity, or limit boundaries when_not_to_use: - For exploratory testing notes that do not depend on boundaries requires_context: - context.testing.negative-testing optional_context: - context.domain.payment.duplicate-charge conflicts: - context.testing.boundary-value-analysis-v1 superseded_by: - context.testing.boundary-value-analysis-v3 --- ``` 支持 YAML 风格块列表的字段有 `tags`、`when_to_use`、`when_not_to_use`、`requires_context`、`optional_context`、`conflicts` 和 `superseded_by`。Renma 支持这些元数据字段的列表，但不支持任意嵌套 map；它不会在 `scan` 期间使用 LLM 推断缺失的依赖项。 目录和扫描诊断会保留元数据的字段级证据。对于像 `requires_context` 和 `optional_context` 这样的块列表依赖项字段， 诊断结果将指向产生边缘或诊断的具体列表项所在行。 ## CI 示例 有关 PR 审查产物，请参见 [`examples/github-actions/renma-ci-report.yml`](examples/github-actions/renma-ci-report.yml)。 ``` name: renma on: pull_request: push: branches: - main jobs: renma: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 with: node-version: 22 - run: npx renma scan . --fail-on high --format json ``` ## 设计理念 Renma 具有坚定的设计主张。 它围绕这样一个理念构建：可重用的 LLM 上下文应该被视为一种软件资产——被拥有、版本化、引用、审查并进行就绪度检查。 这意味着 Renma 偏好结构化的、对 Git 友好的上下文仓库，而不是临时的 prompt 片段或未跟踪的笔记。 ## 设计边界 Renma 有意保持在 Agent runtime 层之下。 Renma 会： - 对 LLM 可消费的仓库资产进行编目 - 验证链接、结构、生命周期状态、安全信号和所有权 - 生成带有文件和行证据的确定性报告 - 通过可审查的 patch 帮助人类和 Agent 修复知识库 Renma 不会： - 为活跃的 Agent 会话选择特定任务的上下文 - 组装 prompt - 将上下文注入到模型调用中 - 执行 Agent 工作流 - 充当提供商网关 - 取代产品、QA、平台或文档的所有权 这个边界使 Renma 作为仓库基础设施保持实用性。Agent 工具可以消费其报告，但该目录依然扎根于 Git、代码审查和确定性检查。 ## 安全诊断 安全诊断 v2 通过面向 LLM 的策略和数据处理诊断，扩展了确定性的 v1 命令检查。Renma 可识别小型策略元数据（例如 `allowed_data`、`network_allowed`、`external_upload_allowed`、`secrets_allowed` 和 `requires_human_approval`）；报告矛盾或违反策略的行为；标记敏感文件和机密材料指令；并检测外部上传、批量共享、云端上传、范围过广的上下文收集以及禁用脱敏的指令。 安全诊断 v3 还会强制执行已批准的目标白名单，例如针对 URL 和类似域名的网络指令的 `approved_network_destinations`。 安全诊断 v4 还可以从 `renma.config.json` 读取仓库级安全策略： ``` { "security": { "approvedDomains": ["github.com", "registry.npmjs.org"], "approvedUploadDomains": ["internal-artifacts.example.com"], "disallowedCommands": ["gh gist create", "pastebin", "webhook.site", "nc"] } } ``` 全局 `approvedDomains` 会与制品本地的 `approved_network_destinations` 结合使用。 上传目标必须通过 `approvedUploadDomains` 单独批准。 安全 profiles 可以在 `security.profiles` 下定义，并由制品通过 `security_profile` 或 `securityProfile` 进行选择。制品本显式拒绝（例如 `network_allowed: false` 和 `external_upload_allowed: false`）仍然比继承的 profile 或仓库许可更严格。 ``` { "security": { "profiles": { "appium-disclosed-local": { "allowedDataClass": "disclosed", "networkAllowed": true, "externalUploadAllowed": false, "secretsAllowed": false, "humanApprovalRequired": true, "allowedData": ["sanitized diagnostics"], "forbiddenInputs": ["secrets", "credentials"], "approvedDomains": ["github.com"], "approvedUploadDomains": [], "disallowedCommands": ["gh gist create"] } } } } ``` Renma 会针对面向 Agent 的操作指令报告确定性的安全发现，例如未固定版本的远程脚本、不安全的特权命令、可预测的临时路径以及类似凭据的命令参数。 这些发现是供审查参考的护栏。它们不能替代机密扫描、SAST、依赖项扫描或人工安全审查。 ## 开发 ``` npm install npm run build npm test ``` 构建后运行本地 CLI： ``` node dist/index.js scan . ``` ## 文档 - [用户手册](docs/user-manual.md) - [诊断参考](docs/diagnostics.md) ## 相关文档 - [architecture.md](architecture.md) 了解更深入的系统模型 - [design.md](design.md) 了解产品和规则设计说明 - [plan.md](plan.md) 了解当前的实现方向

标签：DLL 劫持, Homebrew安装, MITM代理, SOC Prime, 上下文管理, 大语言模型, 开发工具, 知识管理, 自动化攻击