Sunwood-ai-labs/SourceSage

SourceSage CLI

概述

从此仓库检出中使用 SourceSage CLI 为当前仓库或其他本地仓库生成仓库摘要。

优先使用本地检出，而不是假设 sourcesage 已全局安装。在此仓库布局中，SourceSage 工具的根目录是包含此 SKILL.md 的目录。

工作流

1. 确定 SourceSage 工具根目录和目标仓库。

   • 如果用户未指定其他仓库，则分析当前工作区。
   • 如果当前工作区不是 SourceSage 仓库，则从其自己的检出中通过 uv run --directory <sourcesage-root> sage ... 运行 SourceSage。

2. 选择满足请求的最小命令。

   • 当前仓库摘要：uv run sage
   • 当前仓库摘要（精简模式）：uv run sage --lite
   • 当前仓库摘要（日语）：uv run sage -l ja
   • 其他仓库（默认输出在该仓库内）：uv run --directory <sourcesage-root> sage --repo "<target-repo>"
   • 其他仓库（精简模式）：uv run --directory <sourcesage-root> sage --repo "<target-repo>" --lite
   • 其他仓库（显式输出目录）：uv run --directory <sourcesage-root> sage --repo "<target-repo>" -o "<output-dir>"
   • 已弃用的差异报告：uv run --directory <sourcesage-root> sage --repo "<target-repo>" --diff

3. 每次运行后验证生成的工件。

   • 仓库摘要：<output-dir>/.SourceSageAssets/Repository_summary.md
   • 已弃用的差异报告：<output-dir>/.SourceSageAssets/RELEASE_REPORT/Report_<latest-tag>.md
   • 打开生成的 Markdown 并总结重要结果，而不是仅报告命令已运行。
   • 在 --lite 模式下，确认摘要保留了树、Git 信息、统计信息和根目录 README 文件，同时省略了 ## File Contents 部分。

4. 报告副作用和命令不匹配。

   • 期望 SourceSage 在 <repo>/.SourceSageignore 不存在时创建它。
   • 将 --ignore-file 视为受支持的忽略覆盖。
   • 除非 CLI 已更新并重新验证，否则不要依赖 --use-ignore，因为当前 CLI 不公开该标志。

命令说明

• 在 SourceSage 仓库内运行 uv run sage，因为 pyproject.toml 定义了 sage 和 sourcesage 两个入口点。
• 在 SourceSage 仓库外运行 uv run --directory <sourcesage-root> sage ...，以便命令使用此检出而不需要全局安装。
• 仅当包已安装且 uv 不可用时，才直接回退到 sourcesage 或 sage。
• 使用 -l ja 或 -l en 设置输出语言。
• 在忽略规则尚未调整或完整文件摘录会使摘要过大时，首次探索使用 --lite。
• 当用户希望工件放在仓库根目录之外时，使用 -o。
• 使用 --repo 从此检出分析另一个仓库。

验证

• 运行所选命令，而不是仅描述它。
• 确认预期的 Markdown 文件存在。
• 读取生成的输出并报告路径以及所产生内容的简短摘要。
• 在更改任何执行指令或提及它的文档后，重新运行确切的命令。

避免

• 不要假设 README 示例在它们与 sourcesage/cli.py 不同时是权威的。
• 当用户请求特定目标且该目标已包含结果时，不要静默覆盖现有工件。
• 当你可以在此仓库中检查 pyproject.toml 和 sourcesage/cli.py 时，不要凭记忆描述 SourceSage 的用法。