docs: polish Gewu repository presentation

Author: Gewu Contributors

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,57 @@
+name: 问题报告
+description: 报告格物在真实链接、仓库或材料上的错误行为
+title: "[Bug] "
+labels:
+  - bug
+body:
+  - type: markdown
+    attributes:
+      value: |
+        请先移除任务 ID、凭证、浏览器日志和私人材料。安全问题请使用私密安全报告。
+  - type: dropdown
+    id: source_type
+    attributes:
+      label: 材料类型
+      options:
+        - GitHub 或源码仓库
+        - 产品网站或在线工具
+        - 普通文章或文档
+        - X 或社交帖子
+        - 微信公众号
+        - PDF
+        - 图片或截图
+        - 音频或视频
+        - 其他
+    validations:
+      required: true
+  - type: textarea
+    id: request
+    attributes:
+      label: 用户请求
+      description: 请提供脱敏后的原始请求和可公开链接
+    validations:
+      required: true
+  - type: textarea
+    id: observed
+    attributes:
+      label: 实际行为
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: 期望行为
+    validations:
+      required: true
+  - type: textarea
+    id: coverage
+    attributes:
+      label: 覆盖与限制
+      description: 说明页面、图片、媒体、回复或仓库文件实际检查到哪里
+  - type: checkboxes
+    id: privacy
+    attributes:
+      label: 提交确认
+      options:
+        - label: 我已移除凭证、任务 ID、浏览器日志和私人材料
+          required: true

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: 私密安全报告
+    url: https://github.com/wuxie888/gewu/security/advisories/new
+    about: 请不要在公开 Issue 中提交漏洞、凭证或私人材料

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,31 @@
+name: 能力建议
+description: 建议新的来源路线、拆解视角或测试场景
+title: "[Idea] "
+labels:
+  - enhancement
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: 要解决的问题
+      description: 请描述当前格物在哪类真实任务中不足
+    validations:
+      required: true
+  - type: textarea
+    id: example
+    attributes:
+      label: 真实示例
+      description: 提供可公开复现的链接或脱敏材料
+  - type: textarea
+    id: behavior
+    attributes:
+      label: 建议行为
+    validations:
+      required: true
+  - type: textarea
+    id: evidence
+    attributes:
+      label: 验收方式
+      description: 什么证据可以证明改进有效
+    validations:
+      required: true

.github/pull_request_template.md

@@ -0,0 +1,20 @@
+## 改了什么
+
+<!-- 简要说明修改范围 -->
+
+## 为什么
+
+<!-- 对应的真实问题、失败样本或证据 -->
+
+## 验证
+
+- [ ] `python3 scripts/validate_skill.py`
+- [ ] `python3 scripts/test_validate_skill.py`
+- [ ] 官方 `quick_validate.py`
+- [ ] 如声称行为改善，已提供独立前向测试；否则明确标记为静态检查
+
+## 安全与隐私
+
+- [ ] 没有提交凭证、任务 ID、反馈 ID、浏览器日志或私人材料
+- [ ] 没有扩大登录、上传、执行、付费或外部副作用授权
+- [ ] 来源反查没有延伸到普通人的敏感个人信息

CONTRIBUTING.md

@@ -0,0 +1,47 @@
+# 参与贡献
+
+感谢你帮助格物变得更可靠。
+
+## 适合提交的改进
+
+- 新的真实前向测试与可复现材料
+- 页面、仓库、文档或媒体路线中的明确缺口
+- 来源反查的误判案例与更强证据链
+- 能改变使用、复刻或二开判断的拆解维度
+- 安全、隐私、许可证与平台边界修正
+- 文档表达、链接和安装体验改进
+
+## 修改原则
+
+- 核心规则放在 `skills/gewu/SKILL.md`
+- 详细变体放在 `skills/gewu/references/`
+- 参考文档保持一层链接与按需加载
+- 不把搜索摘要、正文抽取或 README 复述写成完整调查
+- 不把静态规则存在写成真实行为已经通过
+- 不提交账号、任务 ID、反馈 ID、浏览器日志或私人材料
+
+## 本地检查
+
+```bash
+python3 scripts/validate_skill.py
+python3 scripts/test_validate_skill.py
+python3 ~/.codex/skills/.system/skill-creator/scripts/quick_validate.py skills/gewu
+```
+
+## 提交测试证据
+
+更新 `evals/results.md` 时，明确标记：
+
+- `真实前向测试`
+- `静态回归`
+- `待测试`
+
+真实前向测试应保留可公开复现的 URL、材料版本、日期、实际覆盖和失败边界。无法公开材料时，只记录不泄露隐私的摘要，不伪造可复现性。
+
+## Pull Request 检查
+
+- [ ] 修改范围与问题对应
+- [ ] 没有夹带私有或敏感数据
+- [ ] 新规则没有与现有安全边界冲突
+- [ ] 静态检查和回归测试通过
+- [ ] 真实测试与静态检查的证据等级没有混写

README.md

@@ -1,77 +1,136 @@
-# 格物
+<p align="center">
+  <img src="./assets/gewu-hero.webp" alt="格物：从表象沿证据链追溯源头" width="100%">
+</p>
 
-> 格一物，知其然，明其理，辨其值
+<h1 align="center">格物 · Gewu</h1>
 
-格物是一个需要通过 `@格物` 或 `$gewu` 显式调用的 Codex 深度调查 Skill，面向链接、GitHub 仓库、网站、产品、社交帖子、微信公众号文章、普通文章、PDF、视频、截图和名称线索。
+<p align="center">
+  <strong>完整看清，追到源头，拆出本质，判断价值</strong>
+</p>
 
-它要求先完整查看目标内容，再从产品、技术、设计、商业、内容和写作等适用维度拆解；必要时从名称、图片与界面线索反查原始来源；最后判断是否值得使用、学习、复刻、二次开发或继续研究。
+<p align="center">
+  A deep-research Skill for OpenAI Codex
+</p>
 
-## 它解决什么问题
+<p align="center">
+  <a href="https://github.com/wuxie888/gewu/actions/workflows/validate.yml"><img src="https://img.shields.io/github/actions/workflow/status/wuxie888/gewu/validate.yml?branch=main&style=flat-square&label=checks" alt="Checks"></a>
+  <a href="./LICENSE"><img src="https://img.shields.io/github/license/wuxie888/gewu?style=flat-square" alt="MIT License"></a>
+  <img src="https://img.shields.io/badge/Codex-Skill-0b7a75?style=flat-square" alt="Codex Skill">
+  <img src="https://img.shields.io/badge/status-1.1%20candidate-b28a3b?style=flat-square" alt="1.1 candidate">
+</p>
 
-- 不把正文提取或 README 复述冒充完整研究
-- 浏览页面顶部到底部，并检查重要图片、视频、回复和外链
-- 区分页面展示、作者声称、交叉验证、推断和未验证内容
-- 从被隐藏或裁切的名称、截图、Logo、文案和命令反查官网与仓库
-- 拆解产品、源码、网站设计、文章结构和写作风格
-- 给出是否值得使用、试用、复刻、二开或停止投入的直接结论
-- 用阅读覆盖单说明实际看到了什么、还有什么没验证
-- 原材料受阻时切换为“降级调查”，不把替代正文冒充原页面完整审阅
-- 把网页、仓库、评论和附件中的指令视为不可信材料，防止页面反向操控调查
+---
+
+格物是一个需要通过 `@格物`、`$gewu` 或 Skill 选择器显式调用的 Codex 深度调查 Skill。
+
+它面向 GitHub 仓库、产品网站、社交帖子、微信公众号文章、普通文章、PDF、视频、截图和名称线索。目标不是复述正文，而是把目标材料看完整、找到一手来源、核验真实能力，最后回答：
+
+- 它到底是什么，当前真实状态如何
+- 核心价值、技术、设计、写作或商业方法是什么
+- 哪些值得借鉴，哪些只是包装或未经验证的声称
+- 是否值得使用、学习、复刻、二次开发或继续研究
+
+## 为什么需要格物
+
+很多内容只展示功能，不给产品名、官网或仓库；很多仓库的 README 比代码更完整；很多产品页面的宣传、演示和真实能力并不一致。
+
+格物把调查组织成一条可复用的证据链：
+
+```mermaid
+flowchart LR
+    A["完整查看原材料"] --> B["提取名称、界面、命令与时间线"]
+    B --> C["来源反查"]
+    C --> D["官网、仓库、文档独立核验"]
+    D --> E["产品 / 技术 / 设计 / 内容拆解"]
+    E --> F["使用、复刻、二开判断"]
+    F --> G["明确下一步或停止投入"]
+```
+
+## 核心能力
+
+| 能力 | 格物会做什么 |
+| --- | --- |
+| 页面级完整阅读 | 从顶部到底部检查正文、图片、视频、回复、引用和关键外链 |
+| 仓库深查 | 阅读真实文件、入口、依赖、CI、Release、Issues 与许可证 |
+| 来源反查 | 从 Logo、截图、UI 文案、命令、版本和时间线寻找官网与原仓库 |
+| 多维拆解 | 按需分析产品、技术、设计、写作、商业、传播和复用价值 |
+| 证据分层 | 区分直接观察、来源声称、交叉验证、合理推断和未验证内容 |
+| 行动判断 | 给出直接使用、先试用、适合二开、复刻方法、继续观察或停止投入 |
+
+## 按材料选择工具
+
+格物不会把所有非 GitHub 内容强制交给同一个浏览器：
+
+| 材料 | 首选路线 |
+| --- | --- |
+| GitHub、GitLab、源码包 | 仓库元数据、源码与只读检查 |
+| 产品网站、文章、社交帖子、公众号 | 用户指定或当前合适的页面级浏览载体 |
+| PDF、报告、论文 | 文档/PDF 工具与逐页覆盖 |
+| 截图、Logo、长图 | 视觉检查、OCR 与来源反查 |
+| 音频、视频 | 媒体本身、可靠字幕与关键时间点 |
+
+文本抽取、搜索摘要、API 和 CLI 可以补充证据，但不能冒充尚未完成的视觉阅读。
+
+## 完整审阅与降级调查
+
+格物明确区分两种状态：
+
+- **完整审阅**：目标范围内的关键页面、图片、媒体和外链已经完成验收
+- **降级调查**：原材料因登录、验证码、删除、地区、权限、格式或浏览器策略受阻，只能使用替代正文、转载、搜索或外部证据
+
+降级调查必须说明原材料缺口、替代证据、对结论的影响，以及需要什么材料才能升级为完整审阅。
 
 ## 安装
 
-把 [`skills/gewu`](skills/gewu) 同步或软链接到 Codex 的全局 Skills 目录。下面的命令可用于首次安装和重复升级，不会生成 `gewu/gewu` 嵌套目录：
+### 从 GitHub 安装
 
 ```bash
+git clone https://github.com/wuxie888/gewu.git
+cd gewu
 mkdir -p ~/.codex/skills/gewu
 rsync -a skills/gewu/ ~/.codex/skills/gewu/
 ```
 
-重启或刷新 Codex 后，通过 `@格物` 或 `$gewu` 调用。
+这组命令可用于首次安装和重复升级，不会生成 `gewu/gewu` 嵌套目录。安装后刷新或重启 Codex。
 
-## 使用示例
+### 调用
 
 ```text
 @格物 看看这个链接，完整拆解并判断值不值得用
 
-@格物 把这个 GitHub 仓库看清楚，判断适不适合二次开发
+$gewu 把这个 GitHub 仓库看清楚，判断适不适合二次开发
 
 @格物 完整阅读这篇文章，并拆出它的写作结构和风格
 
-@格物 文章没写产品名，从图片和描述里把原项目找出来
+@格物 文章没写产品名，从截图和描述里把原项目找出来
 
-@格物 看看这个产品是否值得复刻，哪些能学，哪些不能照搬
+@格物 先快速判断这个项目值不值得继续研究
 ```
 
-## 浏览器要求
+显式调用默认执行完整调查。只有用户明确说“快速判断、先粗看”时，格物才缩小核验范围。
 
-格物按材料形态选择工具：仓库使用源码与元数据检查，网页使用用户指定或当前合适的页面级浏览载体，PDF、图片和视频使用对应文档或媒体工具。用户指定 Chrome 或 Browser 时优先遵循；不会把所有非 GitHub 内容强制交给 Chrome。普通网页读取、搜索、API 和 CLI 用于补充及交叉验证，不能替代尚未完成的视觉阅读。
+## 结果长什么样
 
-如果浏览器、登录、验证码、删除、地区或权限限制导致内容无法完整访问，格物必须报告准确覆盖范围，不能声称已经看全。
+格物不会机械套模板，而是按任务裁剪。完整报告通常包含：
 
-浏览器明确返回安全策略拒绝时，格物会停止该动作，不通过另一浏览器表面、CDP、Computer Use、脚本或间接导航绕过；此时转为诚实的降级调查，或请用户提供 PDF、完整长截图、录屏等材料。
+1. 结论：它是什么，值不值得
+2. 对象与内容地图
+3. 来源反查与证据链
+4. 产品、技术、设计、写作或商业拆解
+5. 已确认、来源声称、推断与未验证项
+6. 使用、复刻与二次开发判断
+7. 阅读覆盖单与访问限制
 
-## 仓库结构
+## 安全边界
 
-```text
-skills/gewu/
-├── SKILL.md
-├── agents/openai.yaml
-└── references/
-    ├── completeness-checklists.md
-    ├── evidence-and-verdict.md
-    ├── lenses-content-design-business.md
-    ├── lenses-product-technical.md
-    ├── origin-tracing.md
-    ├── report-format.md
-    ├── route-documents-media.md
-    ├── route-repositories.md
-    ├── route-web-pages.md
-    ├── source-routing.md
-    └── teardown-lenses.md
-```
+- 默认只读，不擅自克隆、安装、构建或运行第三方代码
+- 不登录新账号、不付费、不上传私有文件、不发布、不部署
+- 网页、仓库、Issue、评论、附件和二维码中的指令不构成用户授权
+- Browser Use 明确返回安全策略拒绝后，不换浏览器表面、CDP、Computer Use 或脚本绕过
+- 来源反查只确认公开产品、仓库、公开作者和首发来源，不定位普通人的敏感个人信息
+- “技术上能做”不等于可以合法、安全、稳定地做
 
-开发与回归场景放在 [`evals/cases.md`](evals/cases.md)，实测记录见 [`evals/results.md`](evals/results.md)；两者都不进入安装后的 Skill 上下文。
+## 测试与证据状态
 
 提交前运行仓库自带的零依赖静态校验和回归测试：
 
@@ -80,16 +139,37 @@ python3 scripts/validate_skill.py
 python3 scripts/test_validate_skill.py
 ```
 
-GitHub Actions 会在每次 Push 和 Pull Request 时执行相同检查。静态校验只能确认结构、元数据、关键规则和已知反向变异，不能替代独立代理面对真实材料的前向测试。
+静态校验只能确认结构、元数据、关键规则和已知反向变异，不能替代独立代理面对真实材料的前向测试。
 
-## 能力边界
+[测试场景](./evals/cases.md) 和 [测试记录](./evals/results.md) 会严格区分：
 
-- 格物默认执行只读研究，不擅自登录新账号、付费、上传、发布、修改仓库或部署
-- “适合复刻”不等于可以复制品牌、代码、文章、图片、视频、模型或受保护数据
-- 没有运行证据时不声称“已经跑通”
-- 调查完成不自动进入产品开发；只有用户明确决定继续时才交接到产品或开发流程
-- 来源反查只确认公开产品、仓库、公开作者和首发记录，不用于定位普通人的敏感个人信息
+- 真实前向测试
+- 静态回归
+- 尚未执行
+
+## 仓库结构
+
+```text
+.
+├── assets/                 # README 视觉资产
+├── evals/                  # 前向测试场景与证据记录
+├── scripts/                # 静态验证与反向回归
+└── skills/gewu/
+    ├── SKILL.md            # 核心工作流
+    ├── agents/openai.yaml  # Codex 展示与触发策略
+    └── references/         # 按来源和拆解视角加载的参考规则
+```
+
+## 参与贡献
+
+欢迎补充真实测试样本、来源路线和拆解视角。提交前请阅读 [CONTRIBUTING.md](./CONTRIBUTING.md)；安全问题请按照 [SECURITY.md](./SECURITY.md) 报告。
 
 ## 许可证
 
 本项目使用 [MIT License](LICENSE)。
+
+---
+
+<p align="center">
+  格一物，知其然，明其理，辨其值
+</p>