diff --git a/.craftkit/.gitignore b/.craftkit/.gitignore index 5a8d09c..6e986cd 100644 --- a/.craftkit/.gitignore +++ b/.craftkit/.gitignore @@ -1,3 +1,3 @@ -# Local CraftKit data +# CraftKit 本地过程资料和可重新生成的缓存不得提交到版本库。 /local/ /cache/ diff --git a/.craftkit/README.md b/.craftkit/README.md index 9acafc8..9f8a735 100644 --- a/.craftkit/README.md +++ b/.craftkit/README.md @@ -1,13 +1,15 @@ # CraftKit 项目资料 -本目录保存 JobRadar 可供 Agent 使用的配置、规范和知识索引。 +本目录保存当前项目可供 Agent 使用的配置、规范、知识和交接内容。 -- `project.json`：项目类型、技术栈、代码边界、依赖标识和已确认命令。 -- `agents/`：项目对 Agent 的补充说明入口。 -- `standards/`：项目开发、测试和交付规范入口。 -- `knowledge/`：经过验证的架构决策和可复用知识入口。 +- `project.json`：项目类型、技术栈、代码边界、依赖标识、命令和文档生命周期默认策略。 +- `agents/`：项目对 Agent 的补充指令。 +- `standards/`：项目自身的开发、测试、文档与 Git 规范。 +- `standards/document-maintenance.md`：长期文档的审核、持续更新、替代和关闭约定。 +- `knowledge/`：经过验证的技术决策和可复用经验。 +- `designs/`：用户明确要求共享或正式交付的设计文档。 - `handoff/`：用户明确选择共享的任务交接。 -- `local/`：当前工作副本的本地上下文，不进入 Git。 +- `local/`：当前工作副本的过程文档、任务记录和本地上下文，不进入 Git。 - `cache/`：可重新生成的缓存，不进入 Git。 共享资料不得包含凭据、个人机器绝对路径或无必要的业务数据。 diff --git a/.craftkit/agents/index.md b/.craftkit/agents/index.md index 8bbe247..caee3a7 100644 --- a/.craftkit/agents/index.md +++ b/.craftkit/agents/index.md @@ -2,6 +2,7 @@ | 主题 | 适用范围 | 入口 | | --- | --- | --- | -| JobRadar Agent 目标、输入输出、工具、状态与人工确认边界 | Agent 运行时、工具和评测相关任务 | `../../docs/agent-contract.md` | +| 项目通用协作要求 | 全仓库任务 | `../../AGENTS.md` | +| 岗位研究 Agent 契约 | Agent 运行时、工具和评测任务 | `../../docs/agent-contract.md` | -项目级通用协作要求见仓库根目录 `../../AGENTS.md`。 +新增补充说明时，应记录适用目录、触发条件和文件路径。 diff --git a/.craftkit/knowledge/index.md b/.craftkit/knowledge/index.md index e6b9920..8f210da 100644 --- a/.craftkit/knowledge/index.md +++ b/.craftkit/knowledge/index.md @@ -1,10 +1,18 @@ # 项目知识索引 +当前可复用的项目知识以已存在的项目文档为证据入口： + | 主题 | 内容 | 证据入口 | | --- | --- | --- | | 项目架构 | 目标架构、模块职责、数据边界和部署边界 | `../../docs/architecture.md` | -| Agent 契约 | 单 Agent 起步、类型化工具、状态、证据与人工确认边界 | `../../docs/agent-contract.md` | +| Agent 契约 | 单 Agent、类型化工具、状态和人工确认边界 | `../../docs/agent-contract.md` | | 工程路线 | 分阶段交付范围和进入下一阶段的条件 | `../../docs/roadmap.md` | -| 第一阶段工程基线 | 数据库与工程实施决策 | `../../docs/engineering-baseline/dev-plan.md` | +| 第一阶段工程基线 | 数据库、工程实施决策和验收要求 | `../../docs/engineering-baseline/dev-plan.md` | -只收录有证据、适用范围明确且能够复用的技术决策与经验。问题经验和新决策按需建立，避免预建空分类。 +只收录有证据、适用范围明确且能够复用的技术决策与经验。 + +长期知识按 `.craftkit/standards/document-maintenance.md` 保存审核状态并持续更新；过时或历史材料不得作为当前有效依据。 + +- 问题经验按需建立在 `pitfalls/`，不预建空分类。 +- 重要技术决策按需建立在 `decisions/`。 +- 其他长期知识应优先并入已有主题，避免同义平行文档。 diff --git a/.craftkit/project.json b/.craftkit/project.json index 9290ecf..06b5029 100644 --- a/.craftkit/project.json +++ b/.craftkit/project.json @@ -6,78 +6,55 @@ }, "project": { "name": "JobRadar", - "description": "面向个人使用、以 Agent 为核心的智能岗位发现与决策系统", + "description": "面向个人求职者、以 Agent 为核心的智能岗位发现与决策系统。", "type": "web-application" }, "technology": { "languages": [ - { - "name": "Python", - "version": "3.13" - } + "Python 3.13" ], "frameworks": [ { "name": "Django", "version": "6.0.8", "profile": "" + }, + { + "name": "OpenAI Agents SDK", + "version": "0.22.0", + "profile": "" } ], "buildTools": [ - { - "name": "Conda", - "source": "environment.yml" - } + "Conda" ], "databases": [ - { - "name": "SQLite", - "usage": "development and test" - }, - { - "name": "PostgreSQL", - "usage": "integration and production" - } + "SQLite", + "PostgreSQL" ] }, "code": { "sourceRoots": [ - "." + "JobRadar" ], "packageRoots": [ "JobRadar" ], "modules": [ - { - "name": "project-config", - "path": "JobRadar", - "purpose": "Django project entry points, URL configuration and environment-specific settings" - } + "JobRadar.settings", + "JobRadar.urls" ] }, "dependencies": { "internal": [], "public": [ - { - "name": "playwright", - "version": "1.60.0", - "purpose": "authorized job-page collection" - }, - { - "name": "psycopg", - "version": "3.3.5", - "purpose": "PostgreSQL database driver" - }, - { - "name": "pillow", - "version": "12.2.0", - "purpose": "image processing support" - }, - { - "name": "openai-agents", - "version": "0.22.0", - "purpose": "planned Agent runtime" - } + "playwright==1.60.0", + "psycopg[binary]==3.3.5", + "pillow==12.2.0", + "pytest==9.1.1", + "pytest-django==4.14.0", + "coverage==7.15.4", + "ruff==0.16.4" ] }, "frontend": { @@ -96,12 +73,21 @@ ], "check": [ "python manage.py check", - "python manage.py makemigrations --check --dry-run" + "python manage.py makemigrations --check --dry-run", + "ruff check ." ] }, "documents": { + "workRoot": ".craftkit/local/tasks", + "designRoot": ".craftkit/designs", "archiveRoot": "docs/archive", - "archiveRules": [] + "archiveRules": [], + "lifecycle": { + "onTaskComplete": "preview", + "localRetentionDays": 7, + "trackedFiles": "review-required", + "personalConfig": "retain" + } }, "guidance": { "agentIndex": ".craftkit/agents/index.md", diff --git a/.craftkit/standards/document-maintenance.md b/.craftkit/standards/document-maintenance.md new file mode 100644 index 0000000..bf432c1 --- /dev/null +++ b/.craftkit/standards/document-maintenance.md @@ -0,0 +1,31 @@ +--- +reviewStatus: pending +reviewedAt: null +replacedBy: null +--- + +# 文档维护规范 + +## 适用范围 + +本规范适用于项目正式需求、生效设计、项目规范和长期知识。过程草稿按任务需要维护，不强制逐份审核；历史归档保留当时快照，不作为当前依据。 + +## 创建与更新 + +- 任务开始时查找相关已有文档，优先更新现有权威内容，不创建同义平行版本。 +- 新建或实质修改长期文档后，将文档自身的 `reviewStatus` 标为 `pending`。 +- 项目已有审批结果可以直接作为审核依据；通过后标为 `approved`。 +- 已知文档与需求、实现或新证据不一致时标为 `outdated`；更新后回到 `pending` 并重新审核。 +- 排版、错字、链接修复和不改变含义的调整不改变审核状态。 + +## 状态与替代 + +项目没有既有元数据格式时，在文档 Frontmatter 使用 `reviewStatus`、`reviewedAt` 和 `replacedBy`。旧文档缺少状态时视为尚未确认，只在实际使用或修改时补齐。 + +新版替代旧版时更新索引和引用，并通过 `replacedBy` 指向当前版本。旧版根据历史价值归档或删除；归档发现错误时补充勘误和新版链接，不改写历史事实。 + +## 任务关联与关闭 + +本地 `task.json` 记录本次创建、更新或引用的文档。关联旧文档不转移所有权，也不产生删除权限。 + +任务关闭前检查本次实现影响的长期文档已经同步。需要作为当前依据的文档必须为 `approved`；`pending` 或 `outdated` 文档应完成处理，无法处理时列入延后清单并说明影响。 diff --git a/.craftkit/standards/index.md b/.craftkit/standards/index.md index 4286607..8b99e86 100644 --- a/.craftkit/standards/index.md +++ b/.craftkit/standards/index.md @@ -2,10 +2,11 @@ | 主题 | 适用范围 | 规则入口 | 优先级 | | --- | --- | --- | --- | -| AI 开发流程、验证与交付 | 全仓库开发任务 | `../../docs/development-guide.md` | 项目规则 | -| 架构、模块、数据与部署边界 | 设计和实现任务 | `../../docs/architecture.md` | 项目规则 | -| Agent 契约与安全边界 | Agent、工具和评测任务 | `../../docs/agent-contract.md` | 项目规则 | -| 阶段范围与实施顺序 | 需求规划和增量实现 | `../../docs/roadmap.md` | 项目计划 | -| Python 格式与静态检查配置 | Python 源码 | `../../pyproject.toml` | 工具配置 | +| 文档生命周期 | 正式需求、设计、规范和长期知识 | [文档维护规范](document-maintenance.md) | 项目规则 | +| AI 开发流程 | 全仓库开发、验证与交付 | [AI 开发约定](../../docs/development-guide.md) | 项目规则 | +| 架构与数据边界 | 设计和实现任务 | [架构设计](../../docs/architecture.md) | 项目规则 | +| Agent 安全边界 | Agent、工具和评测任务 | [Agent 契约](../../docs/agent-contract.md) | 项目规则 | +| 阶段实施顺序 | 需求规划和增量实现 | [实施路线图](../../docs/roadmap.md) | 项目计划 | +| Python 质量配置 | Python 源码 | [工具配置](../../pyproject.toml) | 工具配置 | -未覆盖主题可由 `guidance` 查询中性公共基线。规划内容不能替代已确认的当前实现规则。 +新增规范时记录主题、适用范围、规则文件和优先级；未覆盖主题可由 `guidance` 查询中性公共基线。 diff --git a/AGENTS.md b/AGENTS.md index 44cf016..e3cd215 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,30 +1,49 @@ -# JobRadar 项目协作说明 +# 项目协作说明 ## 项目定位 - 项目名称：JobRadar（职途雷达） -- 项目用途：面向个人使用、以 Agent 为核心的智能岗位发现与决策系统 -- 项目类型：Django Web 应用与 Agent 工程 +- 项目用途：面向个人求职者，以 Agent 编排岗位采集、企业调查、规则筛选、评分和结果管理，形成可追溯的岗位发现与决策流程。 +- 项目类型：Django Web 应用，目前处于工程基线阶段。 ## 技术与代码边界 技术栈、源码根、模块和依赖以 `.craftkit/project.json` 为结构化入口。未确认的信息不得自行补全。 -当前项目处于工程基线阶段。只把仓库中已存在的源码和配置视为已实现能力；README、架构文档和路线图中的后续模块均属于规划，不能描述为已完成。 +- 当前语言为 Python 3.13，Web 框架为 Django 6.0.8。 +- Django 配置位于 `JobRadar/settings/`，开发、测试、集成和生产环境必须使用对应配置。 +- 业务模块按 `docs/architecture.md` 的边界增量建立，不提前创建尚不能验证的空业务模块。 +- 框架记录精确版本和已存在的公共 profile；普通开发只使用当前 profile，升级或版本比较任务才读取源、目标两个版本。 ## 项目资料 +- 项目说明：`README.md` +- 架构设计：`docs/architecture.md` +- Agent 契约：`docs/agent-contract.md` +- 实施路线图：`docs/roadmap.md` +- AI 开发约定：`docs/development-guide.md` - Agent 补充说明：`.craftkit/agents/index.md` - 项目规范：`.craftkit/standards/index.md` - 可复用知识：`.craftkit/knowledge/index.md` -- 项目总览：`README.md` +- 共享设计文档：`.craftkit/designs/`；开发中过程文档使用 `.craftkit/project.json` 配置的 `documents.workRoot`。 +- 文档维护规则：`.craftkit/standards/document-maintenance.md`；修改实现时检查并同步受影响的长期文档。 ## 工作约束 +- 所有回答、项目文档和代码注释使用中文。 +- 修改前先说明方案；复杂改动取得确认后执行，简单改动可以直接处理，但必须说明调整内容。 +- 新增或修改代码时沿用相邻代码的注释格式，并为关键边界、失败路径和不直观逻辑提供详尽注释。 - 修改前先阅读与目标目录和任务主题相关的项目资料。 -- 区分明确项目规则、公共建议、规划目标和从代码观察到的现状。 -- 采用增量、小步、可验证的实现方式，不一次性生成所有规划模块。 +- 区分明确项目规则、公共建议和从代码观察到的现状。 - 不提交凭据、个人机器路径、本地状态或可重新生成缓存。 -- 不伪造 Agent 浏览、查询、工具调用、入库结果或验证结论。 -- 高风险或不可逆操作必须由用户确认；不得自动投递简历或联系招聘人员。 +- 外部采集必须遵守授权范围、站点条款和频率限制，不绕过验证码、登录保护或访问控制。 +- 第一版不自动投递简历或联系招聘人员；高风险或不可逆操作必须经过人工确认。 - 发现规范冲突、信息缺失或多种并存风格时先向用户说明。 + +## 验证要求 + +- Django 配置检查：`python manage.py check` +- 自动化测试：`python manage.py test` +- 迁移完整性：`python manage.py makemigrations --check --dry-run` +- 静态检查：`ruff check .` +- 项目依赖默认在名为 `JobRadar` 的 Conda 环境中运行；若当前解释器缺少依赖，应先确认环境是否已同步。 diff --git a/README.md b/README.md index ba1b377..154060b 100644 --- a/README.md +++ b/README.md @@ -43,9 +43,14 @@ JobRadar 是一套面向个人使用、以 Agent 为核心的智能岗位发现 ```text JobRadar/ -├── JobRadar/ Django 项目配置 +├── JobRadar/ Django 项目配置与分环境 settings │ ├── asgi.py -│ ├── settings.py +│ ├── settings/ +│ │ ├── base.py +│ │ ├── development.py +│ │ ├── integration.py +│ │ ├── production.py +│ │ └── test.py │ ├── urls.py │ └── wsgi.py ├── docs/ 架构与实施文档 @@ -145,7 +150,7 @@ python -m playwright install chromium ## 配置原则 - 本地开发密钥、数据库密码、招聘网站 Cookie 和模型 API Key 不得提交到 Git。 -- 当前 `settings.py` 仍是 Django 生成的开发配置，不可直接用于生产环境。 +- 项目使用 `JobRadar/settings/` 分离开发、测试、集成和生产配置；部署时必须显式选择生产配置。 - 第一阶段本地开发和自动化测试默认使用 SQLite，数据库文件不得提交到版本库。 - PostgreSQL 通过环境变量按需启用；阶段结束前至少完成一次空库迁移和核心模型测试。 - 远程 PostgreSQL 必须使用 TLS、项目专属数据库和低权限账号，自动化测试不得连接生产库。 @@ -215,4 +220,4 @@ JobRadar 仅用于个人岗位信息整理与求职辅助。使用前应确认 当前版本：`0.1.0-dev` -当前阶段：架构与Agent契约已经确定，下一步由AI直接实现阶段一工程基线。 +当前阶段：架构与 Agent 契约已确定，阶段一的配置与依赖基线已落盘，下一步是用户认证与数据归属设计。