{"id":51910726,"url":"https://github.com/rfdiosuao/first-principles-pathfinder","last_synced_at":"2026-07-27T04:01:25.617Z","repository":{"id":373262061,"uuid":"1312674847","full_name":"rfdiosuao/first-principles-pathfinder","owner":"rfdiosuao","description":"Research competing paths and choose the shortest safe route to a complete, verified outcome.","archived":false,"fork":false,"pushed_at":"2026-07-26T16:24:27.000Z","size":23,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-26T18:17:04.885Z","etag":null,"topics":["automation","codex","codex-skill","decision-making","first-principles","pareto"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rfdiosuao.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-07-26T09:45:43.000Z","updated_at":"2026-07-26T16:26:06.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/rfdiosuao/first-principles-pathfinder","commit_stats":null,"previous_names":["rfdiosuao/first-principles-pathfinder"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/rfdiosuao/first-principles-pathfinder","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rfdiosuao%2Ffirst-principles-pathfinder","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rfdiosuao%2Ffirst-principles-pathfinder/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rfdiosuao%2Ffirst-principles-pathfinder/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rfdiosuao%2Ffirst-principles-pathfinder/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rfdiosuao","download_url":"https://codeload.github.com/rfdiosuao/first-principles-pathfinder/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rfdiosuao%2Ffirst-principles-pathfinder/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35935763,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-07-20T02:08:10.276Z","status":"online","status_checked_at":"2026-07-27T02:00:06.776Z","response_time":101,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["automation","codex","codex-skill","decision-making","first-principles","pareto"],"created_at":"2026-07-27T04:01:24.974Z","updated_at":"2026-07-27T04:01:25.601Z","avatar_url":"https://github.com/rfdiosuao.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n\u003ch1\u003e🧭 First-Principles Pathfinder\u003c/h1\u003e\n\n\u003cp\u003e\u003cstrong\u003e先调研，再下注。为 Codex 选择抵达完整结果的最短可验证路径。\u003c/strong\u003e\u003c/p\u003e\n\n\u003cp\u003eResearch competing approaches, test decisive assumptions, and choose the shortest safe path to a complete, verified outcome.\u003c/p\u003e\n\n\u003cp\u003e\n  \u003ca href=\"LICENSE\"\u003e\u003cimg alt=\"MIT License\" src=\"https://img.shields.io/github/license/rfdiosuao/first-principles-pathfinder\"\u003e\u003c/a\u003e\n  \u003cimg alt=\"Python 3.8 or newer\" src=\"https://img.shields.io/badge/Python-3.8%2B-3776AB?logo=python\u0026amp;logoColor=white\"\u003e\n  \u003cimg alt=\"Runtime dependencies: Python standard library only\" src=\"https://img.shields.io/badge/runtime%20dependencies-stdlib%20only-2ea44f\"\u003e\n  \u003ca href=\"https://github.com/rfdiosuao/first-principles-pathfinder/commits/main\"\u003e\u003cimg alt=\"Last commit\" src=\"https://img.shields.io/github/last-commit/rfdiosuao/first-principles-pathfinder\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp\u003e\n  \u003ca href=\"#quick-start\"\u003e快速开始\u003c/a\u003e ·\n  \u003ca href=\"#how-it-works\"\u003e工作原理\u003c/a\u003e ·\n  \u003ca href=\"#verified-example\"\u003e验证示例\u003c/a\u003e ·\n  \u003ca href=\"skills/first-principles-pathfinder/references/decision-protocol.md\"\u003e决策协议\u003c/a\u003e ·\n  \u003ca href=\"https://github.com/rfdiosuao/first-principles-pathfinder/issues\"\u003e反馈问题\u003c/a\u003e\n\u003c/p\u003e\n\n\u003c/div\u003e\n\n---\n\n## 为什么需要它\n\n很多技术任务真正浪费的时间，不在执行，而在**过早选错路线**：\n\n| 常见偏差 | Pathfinder 的处理方式 |\n| --- | --- |\n| 搜到第一个教程就开始部署 | 先覆盖不同机制的路线族，再比较证据 |\n| 默认完整项目比小技巧可靠 | 先盘点本机能力、现有登录态、原生接口与可复用数据 |\n| 单条样本成功就宣称任务完成 | 默认要求 \u003ccode\u003eminimum_coverage = 1.0\u003c/code\u003e，对照完整验收条件 |\n| 用总分掩盖权限、风险或覆盖率缺陷 | 先执行硬约束淘汰，再做 Pareto 剪枝 |\n| 因为已经投入时间而继续死磕 | 忽略沉没成本，用失败证据重新排序 |\n\n这个 Skill 优化的不是代码行数、安装速度或点击次数，而是：\n\n~~~text\n到达完整、合规且经过验证的结果所需的预期总时间\n~~~\n\n适合在部署爬虫、自动化栈、开源项目、托管服务、依赖集成或自研方案**之前**调用。\n\n\u003ca id=\"quick-start\"\u003e\u003c/a\u003e\n\n## 快速开始\n\n### 前置条件\n\n- 支持本地 Skills 的 Codex；\n- Git；\n- Python 3.8+，仅在运行确定性路线比较脚本时需要；脚本不依赖第三方包。\n\n### 1. 安装 Skill\n\n\u003cdetails open\u003e\n\u003csummary\u003e\u003cstrong\u003eWindows PowerShell\u003c/strong\u003e\u003c/summary\u003e\n\n~~~powershell\ngit clone --depth 1 https://github.com/rfdiosuao/first-principles-pathfinder.git\nNew-Item -ItemType Directory -Force \"$env:USERPROFILE\\.codex\\skills\" | Out-Null\nCopy-Item -Recurse \".\\first-principles-pathfinder\\skills\\first-principles-pathfinder\" \"$env:USERPROFILE\\.codex\\skills\\\"\n~~~\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003emacOS / Linux\u003c/strong\u003e\u003c/summary\u003e\n\n~~~bash\ngit clone --depth 1 https://github.com/rfdiosuao/first-principles-pathfinder.git\nmkdir -p ~/.codex/skills\ncp -R first-principles-pathfinder/skills/first-principles-pathfinder ~/.codex/skills/\n~~~\n\n\u003c/details\u003e\n\n如果目标目录已经存在，请先备份旧版本，再进行更新。安装后新建一个 Codex 任务或重启 Codex，使技能列表重新载入。\n\n### 2. 直接调用\n\n~~~text\n使用 $first-principles-pathfinder，先调研并比较达到目标的候选路线，再执行最短可验证路径。\n~~~\n\n也可以使用自然语言触发：\n\n~~~text\n先不要部署项目。请调研不同实现机制，用第一性原理找出完成这件事的最短路径，并验证完整结果。\n~~~\n\n### 3. 你会得到什么\n\n- 明确的目标状态、验收条件和硬约束；\n- 至少三类可行机制的候选路线，或对缺失路线的具体排除理由；\n- 事实、推断与待验证假设分离的路线账本；\n- 胜出路线、关键依据、最小判别实验和回退条件；\n- 对最终用户可见结果的完整验证，而不只是“命令运行成功”。\n\n\u003ca id=\"how-it-works\"\u003e\u003c/a\u003e\n\n## 工作原理\n\n~~~mermaid\nflowchart LR\n    A[\"定义终点\u003cbr/\u003e验收条件与硬约束\"] --\u003e B[\"盘点现有能力\u003cbr/\u003e文件、登录态、API、CLI\"]\n    B --\u003e C[\"搜索不同路线族\"]\n    C --\u003e D{\"通过硬约束？\"}\n    D -- \"否\" --\u003e X[\"淘汰\"]\n    D -- \"是\" --\u003e E[\"Pareto 剪枝\"]\n    E --\u003e F{\"关键未知会改变赢家？\"}\n    F -- \"是\" --\u003e G[\"最小判别实验\"]\n    F -- \"否\" --\u003e H[\"执行胜出路线\"]\n    G --\u003e H\n    H --\u003e I{\"完整验收通过？\"}\n    I -- \"是\" --\u003e J[\"交付结果\"]\n    I -- \"否\" --\u003e K[\"更新证据与路线账本\"]\n    K --\u003e C\n~~~\n\n### 八步协议\n\n1. **定义终点**：把请求翻译为可观察的目标状态与验收条件。\n2. **盘点起点**：检查本地工具、已有数据、登录态和原生能力。\n3. **搜索路线族**：比较原生功能、直接接口、轻量组合、完整项目、UI 自动化和人工协作。\n4. **建立账本**：记录证据质量、覆盖率、成功概率、生命周期耗时、风险与可逆性。\n5. **淘汰与剪枝**：违反硬约束的路线直接出局，其余路线进入 Pareto 比较。\n6. **最小实验**：只测试足以改变路线选择的关键未知量。\n7. **有界执行**：赢家失败后更新证据并重新排序，不进入无限调试。\n8. **全量验收**：验证用户真正需要的完整结果，而不是工具是否启动。\n\n预期总耗时模型：\n\n~~~text\nT_expected = 调研 + 安装 + 执行 + 验证 + 清理\n           + (1 - 成功概率) × 失败恢复成本\n~~~\n\n完整性、权限、安全和合法性始终是硬门槛，不能用更短时间抵消。\n\n\u003ca id=\"verified-example\"\u003e\u003c/a\u003e\n\n## 验证示例：公众号评论路线\n\n仓库内置的 [公众号路线账本](skills/first-principles-pathfinder/tests/fixtures/wechat-paths.json) 比较了两种均声称可覆盖全部公开评论的方案：\n\n| 路线 | 覆盖率 | 预期总耗时 | 风险 | 侵入性 | 结果 |\n| --- | ---: | ---: | ---: | ---: | --- |\n| 复用现有登录态的轻量直连 | 100% | 106 分钟 | 1 | 0 | Pareto 前沿，推荐 |\n| 导出器 + 本地代理服务栈 | 100% | 330.5 分钟 | 2 | 3 | 被支配 |\n\n运行示例：\n\n~~~bash\npython -B skills/first-principles-pathfinder/scripts/rank_paths.py \\\n  skills/first-principles-pathfinder/tests/fixtures/wechat-paths.json\n~~~\n\n关键输出：\n\n~~~json\n{\n  \"dominated\": [\"exporter-plus-proxy-stack\"],\n  \"pareto_front\": [\"direct-session-technique\"],\n  \"recommended\": \"direct-session-technique\"\n}\n~~~\n\n这些数字来自仓库的固定测试样例，用于证明决策规则，不是对所有公众号任务的通用性能承诺。\n\n## 路线比较脚本\n\n当存在三个以上严肃候选、约束较多或选择有争议时，把路线写入 JSON 账本并运行：\n\n~~~bash\npython skills/first-principles-pathfinder/scripts/rank_paths.py path/to/ledger.json\n~~~\n\n脚本会：\n\n- 校验输入结构和数值范围；\n- 淘汰硬约束失败、覆盖率不足或成功概率为零的路线；\n- 计算包含失败恢复成本的预期总耗时；\n- 标记 Pareto 前沿和被支配路线；\n- 根据用户明确优先级生成稳定排序。\n\n它不会输出一个掩盖真实取舍的加权总分，也不会替代证据调查与运行时验证。\n\n## 项目资源\n\n| 资源 | 用途 |\n| --- | --- |\n| [SKILL.md](skills/first-principles-pathfinder/SKILL.md) | Codex 触发条件与核心执行流程 |\n| [决策协议](skills/first-principles-pathfinder/references/decision-protocol.md) | 证据分级、路线账本、停止条件和完整案例 |\n| [rank_paths.py](skills/first-principles-pathfinder/scripts/rank_paths.py) | 硬约束、Pareto 前沿与稳定排序 |\n| [公众号 fixture](skills/first-principles-pathfinder/tests/fixtures/wechat-paths.json) | 可复现的路线比较输入 |\n| [单元测试](skills/first-principles-pathfinder/tests/test_rank_paths.py) | 覆盖硬约束、完整率、零概率和确定性排序 |\n\n## 验证\n\n运行全部测试：\n\n~~~bash\npython -B skills/first-principles-pathfinder/tests/test_rank_paths.py\n~~~\n\n当前测试覆盖：\n\n- 违反硬约束的最快路线仍会被淘汰；\n- 部分覆盖路线不能战胜完整路线；\n- 成功概率为零的路线永不推荐；\n- 非法概率返回结构化错误；\n- 相同候选产生稳定排序；\n- 公众号示例选择轻量直连路线。\n\n## 安全边界\n\nPathfinder 不会扩大用户请求本身授予的权限。以下动作在没有明确授权时必须暂停：\n\n- 提交登录凭据或支付；\n- 破坏性文件与系统操作；\n- 修改安全设置或生产环境；\n- 发送消息、发布内容或进行其他对外通信；\n- 访问非公开数据或绕过访问控制。\n\n项目不应被用于违反平台条款、侵犯隐私或抓取未经授权的数据。\n\n## 参与项目\n\n欢迎通过 [Issues](https://github.com/rfdiosuao/first-principles-pathfinder/issues) 提交可复现问题、真实路线案例和协议改进建议，也欢迎直接发起 Pull Request。\n\n提交前请运行单元测试，并确保新增路线没有用速度、便利性或加权分数掩盖硬约束失败。\n\n## License\n\n本项目采用 [MIT License](LICENSE)。\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frfdiosuao%2Ffirst-principles-pathfinder","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frfdiosuao%2Ffirst-principles-pathfinder","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frfdiosuao%2Ffirst-principles-pathfinder/lists"}