49 lines
4.2 KiB
Plaintext
49 lines
4.2 KiB
Plaintext
name: redesign-design-command.issue
|
||
description: |
|
||
当前 `llm-codegen design` 子命令仅能根据 README 文件生成 `design.json`，功能单一，无法满足项目演进过程中对设计文件进行增量维护的需求。
|
||
在实际开发中，开发者可能手动修改了代码文件，或者通过其他工具生成了代码，需要将这些变更同步回 `design.json` 以保持设计文档与代码的一致性。
|
||
因此，需要重新设计 `design` 子命令，使其具备以下能力：
|
||
- 支持指定一个或多个源文件（Python 文件）作为输入，分析其内容并更新 `design.json` 中对应文件的条目（如摘要、依赖、函数列表、类列表等）。
|
||
- 如果指定的源文件在 `design.json` 中不存在，则自动添加新的文件条目。
|
||
- 如果未指定任何源文件，则默认仍然可以基于 README 生成初始 `design.json`（即保留原有功能）。
|
||
- 支持 `--force` 选项以强制覆盖现有条目，而不是合并更新。
|
||
- 提供 `--dry-run` 选项预览将要进行的更改而不实际写入文件。
|
||
- 所有分析过程仍通过 LLM 调用完成，确保生成的摘要、函数/类描述准确反映代码内容。
|
||
- 更新后的 `design.json` 应保持原有结构，且格式良好（缩进等）。
|
||
|
||
这一改进将使 `design` 命令成为维护项目设计文档的实用工具，而不仅仅是初始化工具。
|
||
|
||
affected_files:
|
||
- src/llm_codegen/cli.py
|
||
- src/llm_codegen/core.py
|
||
- src/llm_codegen/design_generator.py # 新建
|
||
- src/llm_codegen/models.py # 可能调整 FileModel 或新增方法
|
||
|
||
acceptance_criteria:
|
||
- 新增命令行选项：
|
||
- `--source` / `-s`：可重复使用，指定一个或多个源文件路径（相对于项目根目录）。
|
||
- `--force`：强制覆盖现有条目，而不是合并（合并策略见下文）。
|
||
- `--dry-run`：仅显示将要做的更改，不实际写入文件。
|
||
- 如果同时指定 `--source` 和 `--file`（原来的 README 参数），则行为需明确定义（例如先基于 README 生成框架，再根据源文件更新，或报错提示只能使用一种模式）。
|
||
- 当指定 `--source` 时，程序应：
|
||
1. 读取现有的 `design.json`（如果存在），否则视为空设计。
|
||
2. 对于每个源文件，读取其内容。
|
||
3. 调用 LLM 分析该文件内容，生成该文件的 `FileModel` 条目（包括 `summary`、`dependencies`、`functions`、`classes`）。
|
||
4. 将生成的条目与现有条目合并（除非使用 `--force`）：
|
||
- 合并规则：如果现有条目存在，则保留原有字段，仅更新 LLM 提供的字段（例如，如果 LLM 只返回了 `functions`，则只更新 `functions`，保留原有的 `summary` 和 `dependencies`；如果 LLM 返回了完整信息，则全部更新）。建议在 prompt 中要求 LLM 返回完整的文件条目，但由程序决定合并逻辑。
|
||
- 如果使用 `--force`，则直接替换整个文件条目。
|
||
5. 如果文件在 `design.json` 中不存在，则直接添加新条目。
|
||
6. 所有文件处理完成后，保存更新后的 `design.json`。
|
||
- 当未指定 `--source` 时，行为与旧版一致：根据 README 生成完整的 `design.json`（覆盖原有）。
|
||
- 为了保证 LLM 分析的质量，system prompt 应明确要求返回符合 `FileModel` 结构的 JSON，并提供示例。
|
||
- 更新 `cli.py` 中的 `design` 命令，添加上述选项，并调用相应的后端逻辑。
|
||
- 在 `core.py` 中现有 `update_file_entry` 方法可被复用或增强，但建议将设计相关的逻辑迁移到新的 `DesignGenerator` 类中（或直接在 `core.py` 中扩展），以保持代码清晰。
|
||
- 添加单元测试覆盖以下场景：
|
||
- 从单个源文件更新现有条目。
|
||
- 从多个源文件同时更新（包括新增和修改）。
|
||
- 使用 `--force` 覆盖已有条目。
|
||
- 使用 `--dry-run` 不实际写入。
|
||
- 未指定 `--source` 时仍能基于 README 生成。
|
||
- 处理不存在的源文件时给出友好错误提示。
|
||
- 确保与现有 `enhance`、`fix` 命令兼容，不会影响它们的正常功能。
|
||
- 所有代码通过 lint 和类型检查，日志记录完整。 |