soovwv/aienvmap

# aienvmap [](https://github.com/soovwv/aienvmap/actions/workflows/ci.yml) [](LICENSE) [](package.json) **AI 优先的 env map + 轻量级 SBOM 协同工具，专为共享开发环境设计。** `aienvmap` 通过轻量级的 env map、轻量级 SBOM、意图日志、时间线和交接机制，帮助多个 AI agent 安全地共享同一个开发环境。它适用于共享服务器、代码库、笔记本电脑或 CI 工作区，在这些场景下，人员或 AI agent 需要相同的环境事实，而无需沉重的锁机制，并且支持无依赖安装。 - 适用：AI agent 共享影响环境的工作。 - 防止：不同的 AI agent 静默安装或假设不同的软件版本。 - 跳过：您只需要完整的合规性 SBOM 扫描器或硬策略锁定管理器。 - AI 信号：共享的 Codex/Claude/Gemini 工作、版本漂移或重复的环境交接。 - SBOM 信号：使用 `sbom --import --write` 附加现有的 CycloneDX/SPDX JSON；aienvmap 仅保留摘要和有限的概要，从不运行扫描器。 - 启动：运行 `npx aienvmap start`；当文件缺失或过期时，它会创建 env map、轻量级 SBOM、状态、摘要、发现入口和仪表板。 - 现有环境：运行 `npx aienvmap reconcile`；它会报告可见的 Node/npm/pnpm/Yarn/Corepack 和 Python/pip/uv/pipx/Conda 安装情况、包位置、清单摘要/样本、项目预期和路由冲突，而不会更改任何内容。使用 `--portable-compare before.json --against after.json --json` 离线比较脱敏后的案例；差异永远不会授权进行更改。 - 运行时路由证据：完整扫描使用有限的 Volta/fnm/nvm/mise 清单和报告的 Node 路径来确定确切的所有权。nvm 根目录会被规范化，因此外部符号链接无法证明控制权；管理器证明永远不会授予移除权限。 - 深度 Python 证据：`reconcile --full-packages` 可选择将稳定的 `pip inspect` 报告汇总为安装程序计数、请求/可编辑计数、摘要和有限的脱敏元数据样本。默认和快速扫描不会运行它。 - Python 管理器证明：相同的显式深度扫描使用离线 uv 清单、有限的 pyenv 根目录/版本以及 mise 安装的 JSON。确切的 uv 解释器、pyenv 前缀或 mise 安装路径匹配会设置 `ownershipProven: true`；`removalAuthorized` 始终保持为 false，并且默认设置保持仅推断。 - Java、.NET、Ruby、Go 和 Rust 保持仅信息提供。Java 候选项包括 PATH/JAVA_HOME/已知根目录以及 Windows 注册表、macOS `java_home` 或 Linux alternatives 来源；不检查包，也绝不自动建议清理。 - Java 身份：每个检测到的运行时会报告选定的 `java.vendor`、`os.arch`、运行时/VM 名称、报告的 `java.home`，以及同级的 `javac` 是否能证明是 JDK。用户/classpath/安全属性不会被保留。 - Java 构建工具路由：项目的 `mvnw`/`gradlew` 包装器优先于 PATH 中的 Maven/Gradle。Maven 报告的运行时和 Gradle 独特的 Launcher/Daemon JVM 证据将被保留；只有完全匹配的 Daemon 主目录才是强有力的证据。不明确或活动命令分歧的路由仅供审查，并且绝不会更改包装器、`JAVA_HOME` 或 PATH。 - Java 管理器证据：仅当 Java 报告的规范主目录仍位于其配置的安装根目录中时，SDKMAN/mise 才会被标记为安装管理器。外部注册和 shims 仅用于路由；jenv 始终仅用于路由，因为它只选择而不是安装 Java。`ownershipProven` 绝不意味着授权移除。 - 可选漂移门控：使用 `aienvmap reconcile --write` 保存已审查的基线，然后在进行环境敏感的 PR 工作之前使用 `aienvmap reconcile --check --json`。退出代码 `2` 表示需要审查；它永远不会授权清理。 `discover` 是只读的，并报告 `aiDiscovery.decision`：`auto-ready` 或 `fallback-required`。`onboard --dry-run` 会在 `onboard` 写入 `AGENTS.md`、`CLAUDE.md` 或 `GEMINI.md` 之前预览微小的限定范围的标记指针；`onboard --uninstall` 仅移除这些标记。自动发现是尽力而为的；如果缺少指针，请从 `start --json` 或 `.aienvmap/discovery.json` 粘贴 `copyPastePrompt`，然后遵循 `sessionUse` 和 `aiEntry`。 前身为 `aienvmp`。今后请使用 `aienvmap`；新的工作区会写入 `.aienvmap/` 产出物。 ## 10秒上手 ``` npx aienvmap start npx aienvmap reconcile npx aienvmap reconcile --check --json npx aienvmap onboard npx aienvmap discover npx aienvmap status npx aienvmap context --json npx aienvmap handoff ``` 在进行影响环境的更改之前： ``` npx aienvmap sbom --json npx aienvmap intent --actor agent:id --session thread:id --action "planned-change" --target dependency --lease-minutes 60 npx aienvmap checkpoint --actor agent:id --summary "dependency-change" --target dependency ``` 在共享服务器上，AI 可以保护基于早期读取做出的决策：从 `aienvmap status --json` 获取 `coordinationRevision`，然后将其通过 `--if-revision ir1:...` 传递给 `intent` 或 `resolve`。如果另一个 AI 先更改了意图日志，aienvmap 会拒绝过期的写入并提示该 AI 刷新。当同一个 AI 标签可以并发运行时，通过 `--session` 传递一个主机/线程标识符，并通过 `--lease-minutes` 传递 5 到 1440 分钟的建议持续时间。同一执行者下的不同会话是独立的冲突所有者；过期状态保持开放以供审查，并且从不授予修改环境的权限。 尝试运行 `npx aienvmap demo`，在不触及您的工作区的情况下查看多 agent 冲突流程。 有关共享服务器的故事，请阅读 [AI 工作区协同案例研究](examples/ai-workspace-case-study.md)。有关推荐标准，请阅读 [AI 采用指南](examples/ai-adoption-guide.md)。 ## 核心 - 阻止 AI agent 静默使用不同的环境假设 - 为每个 AI 提供相同的 env map、轻量级 SBOM、意图日志、时间线和交接 - 在 `.aienvmap/dashboard.html` 中向人类展示相同的状态 - 默认情况下保持建议性和无依赖；严格模式为可选 - 保持轻量级 SBOM 用于协同，而不是完全替代合规性扫描器 - AI 循环：`sync` -> `status` -> `context --json` -> `intent` -> `checkpoint` -> `handoff` - 现有状态循环：`reconcile` -> 审查发现 -> 选择规范工具链 -> 仅进行明确批准的更改 本地模式仅警告。仅对 CI 或明确的人工请求门控使用严格的 doctor 检查。 ## 输出 ``` AIENV.md # Markdown env map for AI agents .aienvmap/discovery.json # smallest AI fallback entry: discovery decision + maintenance routine .aienvmap/status.json # first AI read: clear/review, next command, nextAgent hint .aienvmap/README.md # generated start-here file when AI finds the artifact folder .aienvmap/summary.md # compact AI/CI summary with start-here path .aienvmap/manifest.json # runtime map + light SBOM .aienvmap/sbom.json # light SBOM; optional external evidence summary lives beside it .aienvmap/sbom.cdx.json # CycloneDX-lite export from project manifests .aienvmap/intents.jsonl # planned env changes .aienvmap/timeline.jsonl # append-only change ledger .aienvmap/plan.md # read-only action plan .aienvmap/dashboard.html # human dashboard ``` ## AI 契约 - `schema --json` 在不进行扫描的情况下打印机器可读的契约。 - `start`、`status`、`context`、`reconcile` 和 SBOM 输出共享 `aiDecisionEnvelope`；请首先阅读它，同时 `requiresHumanApprovalBefore` 即使在条件清晰时也仅允许对破坏性操作类别进行审查。 - `reconcile` 还会发出仅用于提案的 `consolidationPlan`：证据、停止条件、回滚要求和批准门控——绝不会发出应用或移除命令。 - `schemaVersion`、`contractVersion`、`stableFrom` 和兼容性规则是明确的。 - `aiAdoptionDecision`、`recommendation.recommendWhen`、`doNotRecommendWhen` 和 `evidenceDocs` 告诉 AI 何时使用、建议或跳过此工具。 - `agentPointers.discovery`、`aiDiscovery.decision`、`sessionUse`、`startupChecklist`、`aiEntry` 和 `copyPastePrompt` 告诉 AI 发现状态是 `auto-ready` 还是 `fallback-required`。 - `.aienvmap/discovery.json`、`discovery.json.maintenance`、`agentDiscovery.sessionStart` 和 `readOrder` 为仅支持 schema 或 Markdown 优先的 agent 提供备用启动路径。 - `environmentChangeProtocol`、`operationalSafety`、`followUpPlan`、`collaboration`、`coordination` 和 `agentActivity` 使共享更改保持建议性；`followUpPlan` 在需要时指向同步、状态或交接。 - `coordinationRevision` 为意图和解决写入启用可选的比较和交换保护，而无需守护进程、数据库或运行时依赖。 - 可选的意图 `session` 和有限的租约证据可区分共享服务器上的并发 AI 会话；过期是建议性的，从不授权清理或更改。 - `start`、`status` 和 `context` 公开无样本的 `externalSbom` 信号；过期或组件漂移会引发建议性审查，而缺失证据和身份回退则保持非阻塞状态。 - `qualitySignals`、`releaseGate` 和 `releaseReadiness` 公开了对 AI 友好的、轻量级的、批处理的稳定契约门控。 - 在 `0.2.0` 之后，已记录的 JSON 字段保持向后兼容；新字段是附加的。 ## 命令 ``` aienvmap onboard # install Codex/Claude/Gemini pointers and sync aienvmap start # one-command AI startup + copy-paste prompt aienvmap sync # update env map, discovery, start-here README, status, summary, SBOM, dashboard aienvmap status # 5-line env decision with start-here path aienvmap context --json # AI decision contract aienvmap sbom --json # light SBOM; add --import --write for an external evidence reference aienvmap plan --write # read-only action plan aienvmap handoff --record # next-agent summary aienvmap intent # record planned env change aienvmap checkpoint # record + sync + status + handoff after env change aienvmap doctor --strict security|policy|coordination|all aienvmap schema --json # stable output contract for AI/CI consumers aienvmap onboard --agents cursor,copilot ``` ## CI GitHub Action 会写入发现、状态、摘要、schema、doctor、plan、SBOM 和仪表板产出物。`strict: "off"` 会报告警告而不会使任务失败。请参阅 [examples/github-action.yml](examples/github-action.yml)。 `reconcile-check` 默认为 `off`。仅在有经过审查的 `.aienvmap/reconcile.json` 的稳定工作站或自托管 runner 上启用它；临时托管 runner 合理地拥有不同的运行时清单。 ``` - uses: soovwv/aienvmap@main with: write-status: "true" write-plan: "true" write-sbom: "true" write-summary: "true" reconcile-check: "off" strict: "off" ``` ## 发布策略 - `0.1.x` 是从 `aienvmp` 重命名后干净的 `aienvmap` 原型系列。 - `0.2.x` 开启稳定的 AI 工作区契约。 - npm 发布采用手动门控和批处理；工作流要求最新的 main 分支、匹配的 `v` 标签、未发布的版本、OIDC 来源以及发布后的注册表完整性验证。 - 默认的发布决策为 `hold`；仅在批处理了几个有意义的更改、`npm run release:check` 通过且审查了 `schema --json` 的 `releaseReadiness.currentBatch` 之后才发布。 - `schema --json` 暴露 `releaseGate`、`releaseReadiness.currentBatch`、`contractReview`、`nextStabilizationTasks`、`requiredBeforeStable` 和 `evidenceCommands`。`npm run contract:check` 会对 13 个已记录的 AI JSON 根字段表面的未审查更改执行失败关闭策略。 - 损坏或被取代的版本将被弃用，而不是取消发布。 ## 开发 ``` node --test npm run smoke && npm run contract:check && npm run perf:check npm run release:check npm pack --dry-run ``` [路线图](ROADMAP.md) / [记分卡](SCORECARD.md) / [市场快照](MARKET.md) / [安全性](SECURITY.md) / [故障排除](TROUBLESHOOTING.md) / [修复日志](BUGFIXES.md) / [贡献](CONTRIBUTING.md) / [可移植案例指南](examples/portable-environment-case-guide.md) / [多 agent 冲突演示](examples/multi-agent-conflict.md) Apache-2.0

标签：AI开发协作, GNU通用公共许可证, MITM代理, Node.js, SBOM, SOC Prime, 开发工具, 暗色界面, 环境管理, 硬件无关, 自定义脚本