fcon-tech/portolan

# Portolan [俄语版本](docs/ru/README.md) Portolan 是为 AI 代理和工程领导者提供的本地、只读代码库导航套件。 它在您的机器上运行，读取本地文件，并在代理回答问题之前写入有界证据工件：哪些存储库可见，发现了哪些关系和重复/配置表面，看起来像技术债务，以及什么仍然未知。 Portolan 是景观导航的代理 harness：它为代理提供通过本地证据、显式差距和导入的 OSS 输出的有界路线。 它不是一个编码 harness、就绪门、服务目录、可观察性平台、现代化引擎，也不是 Cursor、Claude、Sourcegraph、Backstage 或企业代码智能工具的替代品。 ## 何时使用 当您希望代理回答以下问题时要使用 Portolan： - 这个存储库或本地软件景观中有什么？ - 从本地证据中可以看到哪些依赖关系和关系？ - 重复的源/配置文件在哪里？ - 哪些环境变量、端口、清单、工作流程、功能标志或秘密引用可见？ - 哪些技术债务候选者可以由本地证据支持？ - 什么是不知名、缺失或未评估的？ 当目标混乱、多存储库、遗留或部分黑盒时，Portolan 特别有用。 ## 您将获得什么 主要工作流程为代理创建一个上下文包： ``` portolan context prepare --root --out /context --profile agent ``` 典型输出： ``` /context/ agent-brief.md answer-contract.md query-plan.md evidence-index.jsonl repos.json tool-registry.json oss-plan.json gaps.jsonl ``` 当您需要一个更完整的地图时，运行： ``` portolan map --root --out /map ``` 典型输出： ``` /map/ run.json coverage.json summary.json graph-index.json graph.json findings.jsonl map.md ``` 从 `summary.json`、`graph-index.json`、`findings.jsonl` 和 `map.md` 开始。 只有在需要详细内容时才打开完整的 `graph.json`。 对于针对现有地图包的有界代理问题，使用： ``` portolan query findings --bundle /map --kind relationships --limit 20 portolan query gaps --bundle /map --limit 20 ``` 在需要查找记录、弱证据状态或稳定的 `portolan://` 引用时，在加载 `graph.json` 之前使用这些查询命令。 ## 快速入门 发布 `v0.1.0` 标签后，使用 Go 安装第一个公共源首次发布： ``` # Requires the published v0.1.0 tag. If this fails, use the source-checkout # route below until the tag is available. go install github.com/fcon-tech/portolan/cmd/portolan@v0.1.0 portolan --version ``` 此命令获取公共模块源并在本地构建 CLI。它不会安装预构建的 Portolan 二进制文件。 在该标签存在之前，或者如果您无法或不应通过 `go install` 获取模块，克隆源签出并构建存储库本地二进制文件： ``` git clone https://github.com/fcon-tech/portolan.git cd portolan scripts/bootstrap-portolan .portolan/bin/portolan --version .portolan/bin/portolan --help .portolan/bin/portolan context prepare --root --out /context --profile agent .portolan/bin/portolan map --root --out /map ``` Portolan 尚未发布可下载的预构建二进制文件。您需要 `go.mod` 中声明的 Go 版本进行源引导。 如果引导失败是因为缺少 Go 或缓存的模块，请参阅 [故障排除](docs/agent/TROUBLESHOOTING.md)。仅在您有意进行网络依赖项下载时： ``` PORTOLAN_BOOTSTRAP_ALLOW_NETWORK=1 scripts/bootstrap-portolan ``` 如果您正在开发 Portolan 本身，您还可以使用： ``` go run ./cmd/portolan context prepare --root --out /context --profile agent go run ./cmd/portolan map --root --out /map go run ./cmd/portolan query gaps --bundle /map --limit 20 ``` 仅在您有意替换现有 Portolan 输出目录时使用 `--force`。 ## 文档路线 如果您不确定先打开哪个文档，请从 [文档入门](docs/onboarding.md) 路线开始。它将人类、代理、Cursor 操作员、OpenCode 操作员和发布审阅者指向每个工作流程的维护表面。 对于更大的命名压力示例，请参阅 [Apache Bigtop 压力示例](docs/demo.md)。它是单个本地目标形状的证据，而不是主要产品路径。 ## 公共路线 这些路线是当前的和边界有限的。一些公共表面是初始社区基础设施，而不是广泛采用或支持的证明。 - 安装：使用上面的 [快速入门](#quick-start)。 - 演示：针对您可以检查的任何本地目标运行 [快速入门](#quick-start)。对于更大的命名示例，请参阅 [Apache Bigtop 压力示例](docs/demo.md)。 - 产品声明：在重用公共措辞之前阅读 [产品声明](docs/product-claims.md)。 - 产品质量：在将报告或表面视为产品就绪之前阅读 [产品质量边界](docs/product-quality-boundary.md) 和 [产品成熟度矩阵](docs/product-maturity.md)。 - 贡献：在打开问题或拉取请求之前阅读 [贡献](CONTRIBUTING.md)。 - 安全：通过 [安全](SECURITY.md) 报告敏感漏洞，而不是公开问题。 - 支持：有关公共支持边界，请参阅 [支持](SUPPORT.md)。 ## 代理 如果您要求 AI 代理使用 Portolan，请将其指向用户代理文档： - [文档入门](docs/onboarding.md) - [代理快速入门](docs/agent/QUICKSTART.md) - [代理快速入门，俄语](docs/agent/QUICKSTART.ru.md) - [安装](docs/agent/INSTALL.md) - [安装，俄语](docs/agent/INSTALL.ru.md) - [安装提示](docs/agent/INSTALL-PROMPT.md) - [安装提示，俄语](docs/agent/INSTALL-PROMPT.ru.md) - [配置](docs/agent/CONFIG.md) - [示例](docs/agent/EXAMPLES.md) - [故障排除](docs/agent/TROUBLESHOOTING.md) 在此存储库上工作的开发代理应遵循 [AGENTS.md](AGENTS.md)。 最安全的可重用指令是 [docs/agent/INSTALL-PROMPT.md](docs/agent/INSTALL-PROMPT.md) 中的可复制提示块。填写三个绝对路径，并将该块发送到代理。 对于更短的运行，将此发送到代理： ``` Install and use Portolan from PORTOLAN_PATH on TARGET_PATH. Write artifacts to OUTPUT_PATH. Follow docs/agent/INSTALL-PROMPT.md, preserve unknown / cannot_verify / not_assessed, and cite local artifact paths for every material claim. ``` 对于俄语代理运行，请使用 [docs/agent/INSTALL-PROMPT.ru.md](docs/agent/INSTALL-PROMPT.ru.md)。 为 `PORTOLAN_PATH`、`TARGET_PATH` 和 `OUTPUT_PATH` 提供绝对本地路径。不要将特定于目标的预期发现添加到提示中。 ## 证据规则 Portolan 不会将缺失的证据转换为信心。结果保留证据状态： - `source-visible`：在源文件中可见。 - `metadata-visible`：在本地元数据、清单或导出的工具输出中可见。 - `runtime-visible`：在提供的本地运行时观察中可见。 - `claim-only`：由人类或工具声明，但未在本地验证。 - `unknown`：没有可用的证据。 - `cannot_verify`：存在证据，但 Portolan 无法验证它。 报告还可能使用 `not_assessed`，当表面未检查或检测器未实现时。 ## 当前边界 当前安全的产品措辞位于 [产品声明](docs/product-claims.md)。 当本地检查通过时，`v0.1.0` 发布表面准备进行公共测试；它不意味着 GitHub 流行度、外部采用、合并批准或广泛的生态系统验证。 重要的限制： - 命名的接受示例是特定于目标形状的证据，而不是主要产品故事。经过验证的 Cursor 比较是在一个固定的本地目标上的无头 Cursor，而不是 UI Cursor/Composer。 - 本地存储库数量不能证明完全继承财产覆盖。 - 除非提供支持的本地运行时观察，否则不会评估运行时服务拓扑；部分观察不能证明完整的拓扑。 - Portolan 有记录的不受信任工件边界和针对所选本地 CLI 风险的专注测试；这不是广泛的安全认证。 - 重复发现需要所选本地工具输出，例如 jscpd/CPD-style JSON。如果没有该输出，重复仍然为 `not_assessed`。 - OSS 验证是证据特定的。Syft/CycloneDX、Semgrep、Repomix、Graphify、jscpd-style JSON 和符号索引 JSON 表面是通过它们的本地 CLI、技能或 MCP 表面产生的有界本地输入，当安装并请求时；Portolan 导入并规范化了输出，而不是包装或替换扫描器。 ## 更多文档 英语： - [文档入门](docs/onboarding.md) - [产品声明](docs/product-claims.md) - [发布指南](docs/release.md) - [产品边界](docs/product-boundary.md) - [证据模型](docs/evidence-model.md) - [关系检测](docs/relationship-detection.md) - [运行时观察](docs/runtime-observations.md) - [安全威胁模型](docs/security-threat-model.md) - [OSS 组成](docs/oss-composition.md) - [Apache Bigtop 压力示例](docs/demo.md) - [贡献](CONTRIBUTING.md) - [安全策略](SECURITY.md) - [支持](SUPPORT.md) - [产品待办事项](docs/product-backlog.md) - [SpecKit 工作流程](docs/speckit-workflow.md) 俄语： - [俄语概述](docs/ru/README.md) - [俄语产品边界](docs/ru/product-boundary.md) ## 开发者检查 对于存储库开发： ``` go test -count=1 ./... jq empty schema/*.json git diff --check ```

标签：AI 代码助手, EVTX分析, 代码依赖, 代码关系, 代码准备, 代码准备助手, 代码准备助手助手, 代码准备工具, 代码准备工具助手, 代码准备工具助手助手, 代码分析, 代码分析助手, 代码分析助手助手, 代码分析工具, 代码发现, 代码可视化, 代码可视化助手, 代码可视化助手助手, 代码地图, 代码审查, 代码审查助手, 代码审查助手助手, 代码导航, 代码导航助手, 代码导航助手助手, 代码导航工具, 代码库管理, 代码搜索, 代码文档, 代码文档助手, 代码文档助手助手, 代码映射, 代码映射工具, 代码映射工具助手, 代码映射工具助手助手, 代码智能助手, 代码智能助手助手, 代码智能工具, 代码环境变量, 代码现代化, 代码现代化助手, 代码现代化助手助手, 代码知识库, 代码知识库助手, 代码知识库助手助手, 代码索引, 代码索引助手, 代码索引助手助手, 代码结构, 代码结构助手, 代码结构助手助手, 代码资产管理, 代码资产管理助手, 代码资产管理助手助手, 代码输出, 代码输出助手, 代码输出助手助手, 凭证管理, 功能标志, 工作流程, 工程领导力, 技术债务, 日志审计, 本地化工具, 秘密引用, 端口管理