Skip to content

Commit d60b7c3

Browse files
sherlock0717sherlock0717
authored
revamp: publish detailed analysis, psychology methods, and project brief
Expand PsyLens into a complete public analysis case with detailed findings, psychology-informed coding, cleaning methods, reliability evaluation, normalized public data, a substantive project brief, and repository-wide documentation and CI fixes.
1 parent 6fa628f commit d60b7c3

42 files changed

Lines changed: 4453 additions & 1489 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.gitattributes‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
*.py text eol=lf
2+
*.md text eol=lf
3+
*.html text eol=lf
4+
*.css text eol=lf
5+
*.json text eol=lf
6+
*.jsonl text eol=lf
7+
*.yaml text eol=lf
8+
*.yml text eol=lf
9+
*.csv text eol=lf
10+
*.docx binary

‎.github/workflows/ci.yml‎

Lines changed: 41 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@ name: Public Release CI
22

33
on:
44
push:
5-
branches: ["release/public-v2", "main"]
5+
branches: ["main"]
66
pull_request:
77
workflow_dispatch:
88

@@ -27,43 +27,59 @@ jobs:
2727
run: |
2828
python -m pip install --upgrade pip
2929
pip install -r requirements.txt
30-
pip install pytest ruff python-docx
3130
3231
- name: Compile Python files
33-
run: python -m compileall demo/src pipeline tools/run_demo.py
32+
run: python -m compileall demo/src pipeline tools tests demo/tests
3433

35-
- name: Ruff - Demo source
36-
run: ruff check demo/src
34+
- name: Ruff - Demo
35+
run: ruff check demo/src demo/tests tools/run_demo.py
3736

38-
- name: Ruff - Demo tests
39-
run: ruff check demo/tests
40-
41-
- name: Ruff - Pipeline templates
37+
- name: Ruff - Pipeline
4238
run: ruff check pipeline
4339

44-
- name: Ruff - Demo entry
45-
run: ruff check tools/run_demo.py
40+
- name: Ruff - Public normalization
41+
run: ruff check tools/normalize_public_dataset.py
4642

47-
- name: Ruff - Public release tests
48-
run: ruff check tests
43+
- name: Ruff - Public analysis
44+
run: ruff check tools/summarize_public_analysis.py
4945

50-
- name: Demo tests
51-
run: python -m pytest demo/tests -q
46+
- name: Ruff - Project brief
47+
run: ruff check tools/build_project_brief_docx.py
5248

53-
- name: Public files and counts
54-
run: python -m pytest tests/test_public_release.py::test_required_public_files_exist tests/test_public_release.py::test_public_data_counts_and_fields -q
49+
- name: Ruff - Other tools
50+
shell: bash
51+
run: |
52+
files=$(find tools -maxdepth 1 -name '*.py' \
53+
! -name 'run_demo.py' \
54+
! -name 'normalize_public_dataset.py' \
55+
! -name 'summarize_public_analysis.py' \
56+
! -name 'build_project_brief_docx.py' -print)
57+
if [ -n "$files" ]; then ruff check $files; fi
58+
59+
- name: Ruff - Tests
60+
run: ruff check tests
5561

56-
- name: Public URL scan
57-
run: python -m pytest tests/test_public_release.py::test_public_data_contains_no_external_urls -q
62+
- name: Test suite
63+
run: python -m pytest demo/tests tests -q
5864

59-
- name: Public manifest hashes
60-
run: python -m pytest tests/test_public_release.py::test_public_manifest_matches_files -q
65+
- name: Normalize public data smoke
66+
run: python tools/normalize_public_dataset.py --source-dir data/public --output-dir artifacts/normalized_public
6167

62-
- name: Page and showcase checks
63-
run: python -m pytest tests/test_public_release.py::test_page_copy_is_public_facing tests/test_public_release.py::test_showcase_is_main_ready_and_clean -q
68+
- name: Analysis summary smoke
69+
run: python tools/summarize_public_analysis.py --public-dir data/public --output artifacts/public_analysis_summary.json
6470

65-
- name: README and DOCX checks
66-
run: python -m pytest tests/test_public_release.py::test_readme_uses_public_release_paths tests/test_public_release.py::test_project_brief_is_readable_docx -q
71+
- name: Project brief smoke
72+
run: python tools/build_project_brief_docx.py --output artifacts/PsyLens_project_brief.docx
6773

6874
- name: Demo smoke
6975
run: python tools/run_demo.py --provider mock --output artifacts/demo/ci
76+
77+
- name: Upload QA artifacts
78+
uses: actions/upload-artifact@v4
79+
with:
80+
name: psylens-ci-${{ matrix.os }}
81+
path: |
82+
artifacts/public_analysis_summary.json
83+
artifacts/PsyLens_project_brief.docx
84+
artifacts/demo/ci
85+
if-no-files-found: error

‎.github/workflows/pages.yml‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -28,12 +28,15 @@ jobs:
2828
run: |
2929
python -m pip install --upgrade pip
3030
pip install -r requirements.txt
31-
pip install pytest ruff python-docx
3231
3332
- name: Validate public release
3433
run: |
35-
ruff check demo/src demo/tests pipeline tools/run_demo.py tests
34+
python -m compileall demo/src pipeline tools tests demo/tests
35+
ruff check demo/src demo/tests pipeline tools tests
3636
python -m pytest demo/tests tests -q
37+
python tools/normalize_public_dataset.py --source-dir data/public --output-dir artifacts/normalized_public
38+
python tools/summarize_public_analysis.py --public-dir data/public --output artifacts/public_analysis_summary.json
39+
python tools/build_project_brief_docx.py --output artifacts/PsyLens_project_brief.docx
3740
python tools/run_demo.py --provider mock --output artifacts/demo/pages
3841
3942
- name: Upload site

‎.github/workflows/public-analysis-export.yml‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
name: Public Analysis Artifacts
2+
3+
on:
4+
workflow_dispatch:
5+
pull_request:
6+
paths:
7+
- "data/public/**"
8+
- "tools/normalize_public_dataset.py"
9+
- "tools/summarize_public_analysis.py"
10+
- "tools/build_project_brief_docx.py"
11+
- "docs/assets/data/**"
12+
- "docs/files/PsyLens_project_brief.docx"
13+
14+
permissions:
15+
contents: read
16+
17+
jobs:
18+
build:
19+
runs-on: ubuntu-latest
20+
steps:
21+
- uses: actions/checkout@v4
22+
- uses: actions/setup-python@v5
23+
with:
24+
python-version: "3.12"
25+
- name: Install dependencies
26+
run: pip install -r requirements.txt
27+
- name: Build normalized public package
28+
run: python tools/normalize_public_dataset.py --source-dir data/public --output-dir artifacts/normalized_public
29+
- name: Build analysis summary
30+
run: python tools/summarize_public_analysis.py --public-dir data/public --output artifacts/public_analysis_summary.json
31+
- name: Build formal project brief
32+
run: python tools/build_project_brief_docx.py --output artifacts/PsyLens_project_brief.docx
33+
- name: Upload public analysis artifacts
34+
uses: actions/upload-artifact@v4
35+
with:
36+
name: psylens-public-analysis
37+
path: |
38+
artifacts/normalized_public
39+
artifacts/public_analysis_summary.json
40+
artifacts/PsyLens_project_brief.docx
41+
if-no-files-found: error

‎README.md‎

Lines changed: 109 additions & 46 deletions
Original file line numberDiff line numberDiff line change
@@ -1,84 +1,147 @@
11
# PsyLens
22

3-
PsyLens 是一套社区反馈分析与可靠性评测工作流。当前案例围绕《英雄联盟》海克斯大乱斗社区讨论展开，从三平台公开反馈中整理样本、拆分证据单元、记录主题与机制编码，并通过离线 Demo 检查数据关联和输出复现性。
3+
PsyLens 是一套社区反馈分析与可靠性评测工作流。当前案例围绕《英雄联盟》海克斯大乱斗社区讨论展开，将多平台公开反馈整理为样本与证据单元，再从具体话题、体验机制和数据可靠性三个层面分析。
44

55
- **在线页面**：https://sherlock0717.github.io/PsyLens/
6-
- **项目说明**：[`docs/files/PsyLens_project_brief.docx`](docs/files/PsyLens_project_brief.docx)
6+
- **完整项目说明**：[`docs/files/PsyLens_project_brief.docx`](docs/files/PsyLens_project_brief.docx)
77
- **公开数据**：[`data/public/`](data/public/)
88
- **离线 Demo**：[`demo/`](demo/)
99

1010
## 当前案例
1111

12-
| 项目 | 内容 |
12+
| 项目 | 结果 |
1313
| --- | --- |
14-
| 研究对象 | 海克斯大乱斗社区讨论 |
15-
| 数据来源 | NGA、贴吧、B 站公开反馈 |
16-
| 公开样本 | 360 条，每个平台 120 条 |
17-
| 候选证据 | 927 条，其中 163 条标记为暂不确定 |
18-
| 编码状态 | 历史 AI 编码与离线规则基线均保留来源和复核状态 |
14+
| 数据来源 | NGA、贴吧、B 站公开讨论 |
15+
| 样本设计 | 三个平台各 120 条，共 360 条 |
16+
| 证据单元 | 927 条，平均每条样本 2.575 条 |
17+
| 文本回溯 | 927 条证据均能在对应公开样本中定位 |
18+
| 结构问题 | 孤立证据 0，平台错配 0，重复文本组 0 |
19+
| 日期覆盖 | 120 条有日期，240 条日期为空 |
1920

20-
公开页面与 `data/public/` 使用脱敏副本，不包含原始来源链接。
21+
## 主要分析结果
2122

22-
## 分析流程
23+
### 具体话题
24+
25+
排除 `other_uncertain` 后，共有 441 条证据能够分配具体话题：
26+
27+
- 平衡与数值：270 条，占 61.2%；
28+
- 匹配与对局分配：82 条，占 18.6%；
29+
- 活动与玩法设计：24 条，占 5.4%；
30+
- 成长与养成：20 条，占 4.5%；
31+
- 社区冲突与氛围：18 条，占 4.1%。
32+
33+
### 体验机制
34+
35+
排除 `uncertain` 后，共有 441 条证据能够分配主要体验机制：
36+
37+
- 胜任受挫：308 条，占 69.8%；
38+
- 公平受损：88 条，占 20.0%；
39+
- 信任与沟通落差：24 条，占 5.4%；
40+
- 归属感下降：11 条，占 2.5%；
41+
- 规范与安全风险：10 条，占 2.3%。
42+
43+
### 话题与机制交叉
44+
45+
数量较高的具体组合包括：
46+
47+
- 平衡与数值 × 胜任受挫：138 条；
48+
- 平衡与数值 × 公平受损：35 条；
49+
- 匹配与对局分配 × 胜任受挫：22 条；
50+
- 匹配与对局分配 × 公平受损：16 条；
51+
- 沟通与透明度 × 信任与沟通落差：13 条。
52+
53+
完整分布由 [`tools/summarize_public_analysis.py`](tools/summarize_public_analysis.py) 从公开数据计算，页面读取 [`docs/assets/data/analysis_summary.json`](docs/assets/data/analysis_summary.json) 展示。
54+
55+
## 心理学分析框架
56+
57+
项目采用双层编码：
58+
59+
1. **表层话题**记录反馈正在讨论的问题；
60+
2. **体验机制**记录文本呈现的心理体验方向。
61+
62+
机制层参考胜任需要、公平判断、组织信任、社群归属与规范安全研究，并通过固定纳入、排除和相邻标签区分规则转化为文本编码。详细构念、操作性定义和参考文献见 [`docs/methodology/PSYCHOLOGY_FRAMEWORK.md`](docs/methodology/PSYCHOLOGY_FRAMEWORK.md)。
63+
64+
## 数据处理流程
2365

2466
```text
25-
公开反馈
26-
→ 样本整理
27-
→ 证据单元拆分
28-
→ 主题与机制编码
29-
→ 结构化观察
30-
→ 产品假设
31-
→ 可靠性评测
67+
候选讨论登记
68+
→ 页面与回复采集
69+
→ 原始缓存
70+
→ 规则预清洗
71+
→ 内容筛选与字段规整
72+
→ 平台等额抽样
73+
→ 公开脱敏
74+
→ 证据单元切分
75+
→ 话题与机制编码
76+
→ 完整性与分布审计
3277
```
3378

34-
项目重点检查以下问题：
79+
关键操作包括：删除回复头、引用残留、图片路径和多余空白；移除空文本与低信息噪声；删除来源链接和账号定位字段；按标点切分证据；检查证据文本是否能在父样本中逐字定位；扫描重复、空值、URL 和非法标签。
80+
81+
详细字段、清洗规则和复现命令见 [`docs/methodology/DATA_CLEANING_AND_CODING.md`](docs/methodology/DATA_CLEANING_AND_CODING.md)。
82+
83+
## 可靠性评测
84+
85+
评测分为五组：
3586

36-
- 样本和证据是否具有稳定、唯一的编号；
37-
- 证据文本能否关联到对应样本；
38-
- 标签、不确定项和复核状态是否完整记录；
39-
- 洞察和产品假设能否回到支撑证据；
40-
- 相同输入与配置是否产生一致输出。
87+
- **结构完整性**：ID、父样本、平台和文本定位；
88+
- **清洗与隐私**：字段白名单、URL、重复、空值和文件哈希；
89+
- **编码可用性**：合法标签、不确定比例、标签边界和编码来源；
90+
- **分析支撑**：结论是否带有证据、样本量、分母和平台范围；
91+
- **运行复现**：同输入输出一致、manifest 完整、跨平台 CI。
4192

42-
指标定义见 [`evaluation/metrics.yaml`](evaluation/metrics.yaml)，方法说明见 [`docs/evaluation/EVALUATION_METHOD.md`](docs/evaluation/EVALUATION_METHOD.md)。
93+
当前最明显的质量风险是机制不确定率较高：486 / 927，约 52.4%。这项结果提示短文本、上下文依赖和标签边界仍需要更细的编码设计。完整评测方法见 [`docs/evaluation/EVALUATION_METHOD.md`](docs/evaluation/EVALUATION_METHOD.md)。
4394

44-
## 公开文件
95+
## 两种不确定性
4596

46-
- [`data/public/samples_public.csv`](data/public/samples_public.csv)：360 条脱敏样本；
47-
- [`data/public/evidence_public.csv`](data/public/evidence_public.csv)：927 条候选证据；
48-
- [`data/public/public_manifest.json`](data/public/public_manifest.json)：字段、数量和文件哈希；
49-
- [`docs/methodology/MECHANISM_CODEBOOK.md`](docs/methodology/MECHANISM_CODEBOOK.md)：机制编码手册；
50-
- [`docs/methodology/SURFACE_TOPIC_CODEBOOK.md`](docs/methodology/SURFACE_TOPIC_CODEBOOK.md)：主题编码手册；
51-
- [`pipeline/README.md`](pipeline/README.md)：采集与分析流程模板；
52-
- [`docs/files/PsyLens_project_brief.docx`](docs/files/PsyLens_project_brief.docx)：正式项目说明。
97+
公开数据包含两个含义不同的字段：
98+
99+
- `mechanism_label=uncertain`：486 条，表示无法明确判断体验机制；
100+
- `analysis_inclusion_status=included_flagged_uncertain`：163 条，表示证据仍被保留，但纳入时存在上下文或解释风险。
101+
102+
两者分别统计，不能合并为同一“不确定率”。
53103

54104
## 离线 Demo
55105

56106
```bash
57107
python tools/run_demo.py
58108
```
59109

60-
Demo 默认使用确定性 mock provider，不联网，也不调用外部模型。输出写入独立的 `artifacts/` 目录，包括 JSON、Markdown 和 HTML 报告。
110+
Demo 默认使用确定性 mock provider，不联网，也不调用外部模型。输出写入 `artifacts/`，包括 JSON、Markdown、HTML 和 manifest。
111+
112+
生成公开分析汇总：
61113

62-
详见 [`demo/README.md`](demo/README.md)。
114+
```bash
115+
python tools/summarize_public_analysis.py \
116+
--public-dir data/public \
117+
--output artifacts/public_analysis_summary.json
118+
```
119+
120+
规范化公开数据到独立目录：
121+
122+
```bash
123+
python tools/normalize_public_dataset.py \
124+
--source-dir data/public \
125+
--output-dir artifacts/normalized_public
126+
```
63127

64128
## 仓库结构
65129

66130
```text
67-
data/public/ 公开脱敏数据
68-
demo/ 离线运行示例
69-
evaluation/ 指标与阈值定义
70-
pipeline/ 采集、Prompt 和配置模板
71-
docs/ 展示页、方法文档与项目说明
72-
tools/run_demo.py Demo 运行入口
131+
data/public/ 公开脱敏样本、证据与字段说明
132+
demo/ 离线分析示例
133+
docs/index.html GitHub Pages 展示页
134+
docs/methodology/ 心理框架、编码与清洗方法
135+
docs/evaluation/ 评测方法
136+
evaluation/ 指标与失败类型配置
137+
pipeline/ 采集、配置和 Prompt 模板
138+
tools/ 公开数据规范化、统计与 Demo 入口
139+
tests/ 数据、页面与文档校验
73140
```
74141

75-
## 当前状态
142+
## 解释边界
76143

77-
- 公开数据、稳定编号、证据关联和离线 Demo 已完成；
78-
- B 站编码采用离线规则基线，尚未经过真人复核；
79-
- 两条极短证据仍保留为待确认项；
80-
- 结构化观察和产品假设保留草稿状态；
81-
- 产品假设需要结合实验、访谈或上线指标继续验证。
144+
三个平台采用等额抽样，编码来源包含历史 AI 结果与离线规则提案，且证据数量会受到文本长度和切分粒度影响。因此当前分布用于方法审计、探索性分析和后续研究设计，不直接代表总体玩家意见占比，也不构成产品效果或心理状态的因果结论。
82145

83146
## 权利与使用
84147

0 commit comments

Comments
 (0)