docs add pr workflow

Author: joyang1

.github/pull_request_template.md

@@ -0,0 +1,25 @@
+## Summary
+
+- what changed
+- why it changed
+
+## User Visible Changes
+
+- UI / workflow / protocol visualization changes
+- npm / CLI installation changes
+
+## Validation
+
+- [ ] `npm test`
+- [ ] `npm run pack:check`
+- [ ] manual smoke test in browser
+
+## Risks
+
+- request / response parsing
+- tool call / tool response chain
+- workspace mirror / terminal behavior
+
+## Screenshots
+
+- before / after if UI changed

CONTRIBUTING.md

@@ -0,0 +1,119 @@
+# Contributing To codex-viewer
+
+## Branch Strategy
+
+- `main`：稳定分支，只接收已通过验证和代码评审的改动
+- `codex/*`：Codex 或日常开发分支
+- `feat/*`、`fix/*`：也可以保留给人工开发使用
+
+推荐分支命名：
+
+```bash
+codex/<short-description>
+```
+
+例如：
+
+```bash
+codex/real-gpt-trace
+codex/npm-release
+fix/json-modal-scroll
+```
+
+## Local Development Checklist
+
+开始开发前：
+
+```bash
+npm install
+```
+
+提交前至少执行：
+
+```bash
+npm test
+npm run pack:check
+```
+
+如果改动涉及前端界面，建议额外手动检查：
+
+- `codex input`
+- `request visualization`
+- `timeline`
+- `protocol`
+- `view json`
+
+## Pull Request Workflow
+
+1. 从 `main` 创建新分支
+
+```bash
+git checkout main
+git pull
+git checkout -b codex/<short-description>
+```
+
+2. 完成开发与自测
+
+3. 提交代码
+
+```bash
+git add .
+git commit -m "short summary"
+```
+
+4. 推送分支
+
+```bash
+git push -u origin HEAD
+```
+
+5. 创建 Draft PR
+
+PR 标题建议：
+
+```text
+[codex] short summary
+```
+
+6. 在 PR 描述中写清楚：
+
+- 改了什么
+- 为什么要改
+- 用户能看到什么变化
+- 如何验证
+- 是否有风险或已知限制
+
+7. 完成 Code Review 后再转为 Ready for review / 合并
+
+## PR Review Focus
+
+评审时重点看：
+
+- 是否影响请求拦截链路
+- request / response / tool call / tool response 展示是否清晰
+- 多轮上下文是否被正确保留
+- npm CLI 安装与启动是否仍然可用
+- 是否引入了敏感文件、证书、私钥或本地缓存
+
+## Sensitive Files
+
+以下文件或目录不要提交：
+
+- `.codex-viewer/mitm-ca/`
+- `.npm-cache/`
+- `node_modules/`
+- 本地日志、临时文件、证书和私钥
+
+## Release Flow
+
+发布前建议按顺序执行：
+
+```bash
+npm whoami
+npm test
+npm run pack:check
+npm publish --access public
+```
+
+如果账号启用了 2FA，发布时需要补 `--otp=<code>`。

README.md

@@ -38,7 +38,7 @@
 ### 全局安装
 
 ```bash
-npm install -g codex-viewer
+npm install -g @joyang1/codex-viewer
 ```
 
 安装完成后可直接运行：
@@ -50,7 +50,7 @@ codex-viewer --port 3789
 ### 免安装快速运行
 
 ```bash
-npx codex-viewer --port 3789
+npx @joyang1/codex-viewer --port 3789
 ```
 
 ## 前置条件
@@ -161,6 +161,23 @@ node bin/codex-viewer.js --port 3789
 npm run pack:check
 ```
 
+## 协作与 PR 流程
+
+仓库已经补了一套可直接执行的协作流程：
+
+- PR 流程说明：[`CONTRIBUTING.md`](./CONTRIBUTING.md)
+- PR 模板：[`./.github/pull_request_template.md`](./.github/pull_request_template.md)
+
+推荐流程：
+
+1. 从 `main` 拉最新代码
+2. 新建功能分支，例如 `codex/feature-name`
+3. 开发完成后先执行：
+   - `npm test`
+   - `npm run pack:check`
+4. 推送分支并创建 Draft PR
+5. CR 通过后再合并到 `main`
+
 ## 发布到 npm
 
 项目已经准备成可直接发布的 npm CLI 包。正式发布前，建议按下面顺序执行：
@@ -172,16 +189,16 @@ npm run pack:check
 npm publish --access public
 ```
 
-如果 `codex-viewer` 这个 unscoped 包名已被占用，建议改成组织作用域，例如：
+当前仓库默认使用作用域包名：
 
 ```bash
-@your-scope/codex-viewer
+@joyang1/codex-viewer
 ```
 
 对应安装命令会变成：
 
 ```bash
-npm install -g @your-scope/codex-viewer
+npm install -g @joyang1/codex-viewer
 ```
 
 ## 建议在发布前再补一项